Order fulfillment retrieval

Once you have sent orders into Zentail, the next step is to learn when they ship and read back each package’s carrier and tracking number, so you can confirm the shipment on your channel.

What you’ll build

A poller that asks Zentail, every few minutes, for the orders that shipped since it last asked, and confirms each package on your channel.

Before you start

• You hold an access token for the seller. See Authentication.
• You have injected orders into Zentail for that seller.

1. Poll for shipped orders

Request GET /v2/storefront/orders/shipped with the time of your last successful poll:

GET /v2/storefront/orders/shipped?lastUpdatedTs=2026-09-22T14:00:00.000Z

Parameter	Type	Description
lastUpdatedTs	string ($date-time)	Only orders updated at or after this time.
cursor	string	The nextPageCursor from the previous page. Leave it out for the first page.
pageSize	integer	Orders per page. Leave it out for the server default.
salesChannelStatus	string	Narrow further by your channel’s own status for the order.
includeChannelFulfilledOrders	boolean	Include orders your channel fulfilled itself, such as FBA. Off by default, because the seller does not confirm those.

You never ask for a status. The route only ever returns orders whose Zentail status is SHIPPED or PARTIALLY_SHIPPED, and the seller is taken from your token.

Keep one timestamp per token. Query from a minute before it, so a slow write on our side cannot slip between two polls. Once you have processed every page, move the timestamp to the time you sent the first request.

Note

This order data is critical. Poll at least once every 15 minutes, and as often as once every 2 minutes.

Legacy (v1)

Poll GET /v1/salesOrder with lastUpdatedTs and status=SHIPPED,PARTIALLY_SHIPPED. Unlike v2, v1 returns every status unless you pass the filter.

You can also poll each unshipped order on its own with GET /v1/salesOrder/{orderNumber}. It is simpler, but at any real order volume you will hit the throttle limits.

v1 pages differently, through pagination.nextToken. See Pagination.

2. Read each package

Each order carries its line items and one package per tracking number:

{
  "orders": [
    {
      "channelOrderId": "113-4567890-1234567",
      "orderNumber": "10012345",
      "status": "SHIPPED",
      "salesChannelStatus": "Unshipped",
      "lastUpdatedTs": "2026-09-22T14:03:11.000Z",
      "marketplaceId": "ATVPDKIKX0DER",
      "standardServiceLevel": "Standard",
      "lineItems": [
        {
          "lineItemId": "88001",
          "channelLineItemId": "40123456789012",
          "sku": "TSHIRT-RED-M",
          "channelSku": "TSHIRT-RED-M",
          "quantity": "2"
        }
      ],
      "packages": [
        {
          "packageId": "550021",
          "carrier": "UPS",
          "serviceLevel": "Ground",
          "tracking": "1Z999AA10123456784",
          "shippedTs": "2026-09-22T13:58:40.000Z",
          "items": [
            {
              "lineItemId": "88001",
              "sku": "TSHIRT-RED-M",
              "channelSku": "TSHIRT-RED-M",
              "quantity": "2"
            }
          ]
        }
      ]
    }
  ],
  "nextPageCursor": ""
}

• Confirm per package. Send each package’s carrier, serviceLevel and tracking to your channel, with the lines in its items.
• A package can come back on more than one poll. The 1-minute overlap in step 1 means an already-confirmed package can be handed to you again. Track which packageIds you have already confirmed and skip a repeat — this is not only a partial-shipment concern; see step 3.
• Match lines by lineItemId. It is the same id on lineItems and on each package’s items. Use channelLineItemId when your channel wants its own id back.
• Use channelSku for channel-side lookups. It is the SKU your channel listed the line under, and it differs from sku whenever the line is an alias of a catalog product.
• orderNumber, packageId and every quantity are JSON strings. They are 64-bit integers, which a JSON number cannot carry safely. Parse them as integers.
• When a package has no serviceLevel, fall back to the order’s standardServiceLevel.

Keep requesting with cursor set to nextPageCursor until it comes back empty.

Legacy (v1)

The v1 order carries the same information under its packages key. Each package has a carrier, a tracking number and a shipment timestamp, plus a products key listing which SKUs, and how many of each, are inside it.

3. Handle partial shipments

A PARTIALLY_SHIPPED order has shipped some of its units but not all. Confirm the packages it already has. The order comes back on a later poll with more packages as the rest ship, and its status moves to SHIPPED once every unit is in a package. So track which packageIds you have already confirmed, rather than which orders — the same dedup step 2 needs for every order, not only partial ones.

See also

• List shipped orders
• Get an order: one order by its channel order id, Zentail order number or purchase order id, whatever its status.