Orders API

List Orders

Returns a paginated list of orders belonging to the seller bound to your access token. Orders are returned newest first. You can filter by status, date range, and sort direction, and walk large result sets efficiently with cursor pagination.

Only your seller's own orders are ever returned — the seller scope is enforced server-side from your access token and cannot be overridden by any query parameter.

Query Parameters

Example Request

curl -X GET "https://api.mallplus.com/open/v1/orders?status=paid&limit=10" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response — offset mode (no cursor)

{
  "success": true,
  "data": [
    {
      "id": "ord_98765",
      "status": "paid",
      "sellerId": "seller_xyz789",
      "customerId": "cus_001",
      "currency": "PHP",
      "subtotal": 499800,
      "total": 519800,
      "shipping": 20000,
      "paymentStatus": "paid",
      "fulfillmentStatus": "not_fulfilled",
      "created_at": "2026-06-15T16:30:00Z",
      "updated_at": "2026-06-15T17:00:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 10, "total": 87 }
}

Example Response — cursor mode

{
  "success": true,
  "data": [ /* ...orders... */ ],
  "meta": { "limit": 100, "nextCursor": "eyJ0cyI6IjIwMjYtMDYtMTUiLCJpZCI6Im9yZF85ODc2NSJ9" }
}

In cursor mode meta omits page and total; nextCursor appears only when the page is full (an underfilled page signals end-of-list).

Get Order

Returns the full details of a single order, including its line items, fulfillments, and shipping/billing addresses. A request for an order that does not exist, or that belongs to a different seller, returns 404 NOT_FOUND — the two cases are intentionally indistinguishable to avoid leaking the existence of cross-seller orders.

Path Parameters

Example Request

curl -X GET "https://api.mallplus.com/open/v1/orders/ord_98765" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": {
    "id": "ord_98765",
    "status": "paid",
    "sellerId": "seller_xyz789",
    "customerId": "cus_001",
    "currency": "PHP",
    "subtotal": 499800,
    "total": 519800,
    "shipping": 20000,
    "paymentStatus": "paid",
    "fulfillmentStatus": "not_fulfilled",
    "created_at": "2026-06-15T16:30:00Z",
    "updated_at": "2026-06-15T17:00:00Z",
    "shipByDate": "2026-06-17T16:00:00Z",
    "slaBreached": false,
    "items": [
      {
        "id": "item_001",
        "orderId": "ord_98765",
        "productId": "prod_abc123",
        "variantId": "variant_001",
        "title": "Premium Leather Wallet",
        "sku": "WALLET-BLK-001",
        "quantity": 2,
        "unitPrice": 249900,
        "totalPrice": 499800
      }
    ],
    "fulfillments": [],
    "shippingAddress": {
      "name": "Maria Santos",
      "line1": "123 Rizal Avenue",
      "line2": "Unit 4B",
      "city": "Makati",
      "province": "Metro Manila",
      "postalCode": "1200",
      "country": "PH",
      "phone": "(***) ***-4567"
    }
  }
}

The shipping/billing address phone is masked by default. It is returned unmasked only when your access token carries the customer:contact:read scope. Customer email is never exposed.

Get Order Items

Returns the line items for a specific order, including product details, SKU, quantities, and prices. Useful for WMS systems that need to pick and pack individual items. As with Get Order, a missing or cross-seller order returns 404 NOT_FOUND.

Example Request

curl -X GET "https://api.mallplus.com/open/v1/orders/ord_98765/items" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": [
    {
      "id": "item_001",
      "orderId": "ord_98765",
      "productId": "prod_abc123",
      "variantId": "variant_001",
      "title": "Premium Leather Wallet",
      "sku": "WALLET-BLK-001",
      "quantity": 2,
      "unitPrice": 249900,
      "totalPrice": 499800
    }
  ]
}

Order Object

The order object returned by List Orders (as array items) and Get Order (as a single object). Unless noted, all fields except id and status are optional — they appear only when the upstream order carries a value for them.

Customer email is intentionally never exposed in V1; use customerId plus the masked phone for buyer identification.

Ship Order

Ship an order by providing tracking information. The order must be in READY_TO_SHIP status. This is the primary endpoint WMS partners use after picking and packing.

Request Body

Example Request

curl -X POST "https://api.mallplus.com/open/v1/orders/ORD123/ship" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"trackingNumber": "TRK123456789", "trackingCompany": "J&T Express"}'

Cancel Order

Cancel an order that has not yet been shipped. The order must be in READY_TO_SHIP status. A cancellation reason is required for audit purposes.

Request Body

Example Request

curl -X POST "https://api.mallplus.com/open/v1/orders/ORD123/cancel" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer requested cancellation"}'