Fulfillments API

List Fulfillments

Returns a paginated list of fulfillment records for the seller bound to your access token. A fulfillment represents one shipment of one or more items from an order; an order can have multiple fulfillments when it ships in several packages. You can filter by status or parent order, choose a sort direction, and walk large result sets efficiently with cursor pagination.

Only fulfillments belonging to your seller 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 Response — offset pagination (default)

{
  "success": true,
  "data": [
    {
      "id": "ful_01J9WX4K2Q",
      "status": "shipped",
      "orderId": "order_01J9MV7H8S",
      "trackingNumber": "PHJT20260416000123",
      "trackingCompany": "J&T Express",
      "created_at": "2026-04-16T08:00:00Z",
      "updated_at": "2026-04-16T08:05:00Z",
      "items": [
        { "itemId": "item_01J9MV7H8S", "quantity": 2 }
      ]
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1 }
}

Example Response — cursor pagination

{
  "success": true,
  "data": [ /* …same Fulfillment objects… */ ],
  "meta": {
    "limit": 50,
    "nextCursor": "eyJ0cyI6IjIwMjYtMDQtMTZU..."
  }
}

Get Fulfillment

Returns a single fulfillment by ID. Use the id returned from the list endpoint or from a fulfillment.* webhook payload.

The returned object is the partner-safe projection described in Fulfillment Object — carrier-internal fields (e.g. J&T mailno, bill_code, sortingcode) are stripped at the API boundary.

Example Response

{
  "success": true,
  "data": {
    "id": "ful_01J9WX4K2Q",
    "status": "shipped",
    "orderId": "order_01J9MV7H8S",
    "trackingNumber": "PHJT20260416000123",
    "trackingCompany": "J&T Express",
    "created_at": "2026-04-16T08:00:00Z",
    "updated_at": "2026-04-16T08:05:00Z",
    "items": [
      { "itemId": "item_01J9MV7H8S", "quantity": 2 }
    ]
  }
}

Not Found

Returns NOT_FOUND (HTTP 404) when the fulfillment does not exist or belongs to a different seller. A 404 (not 403) is returned for cross-seller IDs so that the existence of another seller's fulfillment cannot be inferred.

{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "Fulfillment not found" }
}

Create Fulfillment

Create a new fulfillment for an order you own. Specify which items are being fulfilled and optionally include tracking information. Supports partial fulfillment — you can fulfill different items in separate shipments.

The request body is validated strictly; unknown keys return VALIDATION_ERROR (HTTP 400). If the parent order does not exist or belongs to another seller, the endpoint returns NOT_FOUND (HTTP 404) for the order — it does not leak the order's existence.

This endpoint is idempotent: send an Idempotency-Key header to safely retry after a network failure without creating duplicate fulfillments.

Request Body

Example Request

curl -X POST "https://api.mallplus.com/open/v1/fulfillments" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9e2a-1b4d-4c8a-9e2f-1234567890ab" \
  -d '{
    "orderId": "order_01J9MV7H8S",
    "items": [{ "itemId": "item_01J9MV7H8S", "quantity": 1 }],
    "trackingNumber": "PHJT20260416000123",
    "trackingCompany": "J&T Express"
  }'

Example Response (HTTP 201)

{
  "success": true,
  "data": {
    "id": "ful_01J9WX4K2Q",
    "status": "pending",
    "orderId": "order_01J9MV7H8S",
    "trackingNumber": "PHJT20260416000123",
    "trackingCompany": "J&T Express",
    "created_at": "2026-04-16T08:00:00Z",
    "items": [{ "itemId": "item_01J9MV7H8S", "quantity": 1 }]
  }
}

Update Fulfillment

Update the status and/or tracking information of an existing fulfillment. Use this to mark a fulfillment as shipped, delivered, or cancelled, and to add or update tracking details. All body fields are optional; send only the ones you want to change.

As with the other endpoints, cross-seller writes return NOT_FOUND (HTTP 404), and the body is validated strictly.

Request Body

Example Request

curl -X PUT "https://api.mallplus.com/open/v1/fulfillments/ful_01J9WX4K2Q" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "trackingNumber": "PHJT20260416000123",
    "trackingCompany": "J&T Express"
  }'

Fulfillment Object

The partner-safe projection of a fulfillment returned by every endpoint on this page. Field names are camelCase. Carrier-internal metadata (e.g. J&T mailno, bill_code, sortingcode, jt_*) is dropped at the API boundary; only tracking_number and tracking_company are forwarded when present inside the internal metadata blob.