Orders

List and fetch orders, confirm shipments with tracking, cancel and refund. Includes which marketplaces order writes actually reach today.

Six endpoints. Reading needs OrdersRead; everything that changes an order needs OrdersWrite.

POST /api/orders/List

Orders, filtered and paged.

{
  "MarketplaceHubOrderIDs": ["6a73..."],
  "OrderStatuses": ["Unshipped"],
  "UpdatedSince": "2026-08-01T00:00:00Z",
  "Limit": 50,
  "Cursor": "6a73...",
  "IncludeCustomerData": false
}

• All filters are optional. Omit everything and you get the first page of everything.
• Limit defaults to 50, maximum 200.
• FromDate and ToDate also exist and bound the same field UpdatedSince does — when the order was last changed, not when it was purchased. The names are historical.

IncludeCustomerData defaults to false. Customer name, phone, email and the shipping address are omitted unless you ask. That is deliberate: a stock-level or order-count integration has no use for them, and the default should not move personal data across the wire for no reason. Ask for it when you are fulfilling; leave it off otherwise.

GET /api/orders/{id}

One order, in exactly the shape it has inside a List response — so one type in your client serves both. Add ?includeCustomerData=true for the customer block.

POST /api/orders/Confirm

Confirms shipment, with carrier and tracking.

{
  "OrderItems": [
    {
      "OrderItemId": "6a73...",
      "ShipDate": "2026-08-05T10:00:00Z",
      "CarrierCode": "RoyalMail",
      "CarrierName": "Royal Mail",
      "ServiceLevel": "Tracked24",
      "TrackingNumber": "AB123456789GB"
    }
  ]
}

The whole batch is validated before any of it runs, so a bad id in the third item cannot leave the first two already confirmed.

POST /api/orders/Cancel and /api/orders/Refund

Same batch shape, keyed by OrderItemId. Cancel takes a CancelReason; Refund takes a Reason, a Currency and the amounts being returned.

Send an Idempotency-Key on refunds especially. Money moves, and a retried refund without a key is a second refund.

POST /api/orders/Update

Attaches your own external order reference to an order. Local bookkeeping — nothing is sent to a marketplace.

Which marketplaces these actually reach

Confirm, Cancel and Refund record the change in MarketplaceHub and hand it to the marketplace's own outbound sync. That sync exists for Amazon only today. On eBay, Shopify and Etsy the change is stored and never sent.

Rather than return a confident 200 for work that will not happen, those responses carry a Warnings entry naming the platform. If you see one, apply the change in that marketplace's own tools too.

{
  "RequestId": "6a73...",
  "Warnings": [
    "EBay order push-back is not implemented yet, so this change is recorded in MarketplaceHub only and will not reach the marketplace. Apply it in the marketplace's own tools as well. See issue #380."
  ]
}

Check Warnings on every write. It is empty on the happy path.