Orders

List and fetch orders, confirm shipments with tracking, cancel and refund: which order writes reach which marketplace, and the one order the API refuses.

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

Reads, writes, and how far a write actually reaches.

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.

FulfilledByMarketplace on each order is true when the marketplace ships the order from its own stock, such as Amazon FBA. You cannot confirm such an order. To list only the orders you have to ship, send "FulfilledByMarketplace": false with "OrderStatuses": ["Unshipped"]. Send true for only the orders the marketplace ships, or leave it out for both.

AmazonMcf on each order is present while Amazon ships the order from your FBA stock by Multi-Channel Fulfillment. It gives State, RequestedAt, the AmazonOrderId, the fee Amazon quoted (FeeTotal, FeeCurrency), LastError and CancelState. Such an order also counts as FulfilledByMarketplace. When Amazon is done, AmazonMcf is absent again and the tracking is on the order's lines.

IsBusinessOrder on each order is true when the buyer is an Amazon Business (B2B) customer, and false for every other order, on every marketplace. To list only those orders, send "IsBusinessOrder": true; send false for every other order, or leave it out for both. MarketplaceHub does not create VAT invoices for these orders; to have Amazon issue them, the seller turns on Amazon's VAT Calculation Service in Seller Central.

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.

BigCommerce cancels whole orders, not single items. Name every item of the order that is not already cancelled or refunded in the same call. A call that leaves one out is refused with a 409 before anything is cancelled, and the error against each item lists the items left out. To give money back for part of a BigCommerce order, refund those items instead.

{
  "code": "conflict",
  "errors": {
    "OrderItems[0].OrderItemId": [
      "BigCommerce cancels whole orders, not single items. Name every item of this order that is not cancelled or refunded in the same call, or refund the items instead.",
      "Items left out: 6a7391c2d4e5f6a7b8c9d0e1."
    ]
  }
}

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.

POST /api/orders/ship-with-amazon

Asks Amazon to ship one order from your FBA stock (Multi-Channel Fulfillment). Amazon ships every line still waiting, and MarketplaceHub sends Amazon's tracking to the selling channel when Amazon ships. Needs the OrdersWrite permission.

{
  "OrderId": "6a73...",
  "DryRun": true
}

Dry-run first. With DryRun true the answer is Amazon's quote: Preview.FeeTotal, the fees by type, the ship and delivery dates and the lines. Nothing is sent.
Without DryRun the answer is Status: "requested" and the AmazonOrderId. Follow the order's AmazonMcf from there.
A second call for the same order sends nothing. It is refused with the reason AlreadySentToAmazon. Send an Idempotency-Key to make a retry safe.
A refusal is a 409 whose errors.Reasons lists codes, for example AmazonStoreInPreview, AddressMissing or LineNotUnshipped.
When your key's writes need approval, the answer is Status: "pending" with a ProposalId, and a person approves it in MarketplaceHub. Approving sends it only at the fee on the card.

POST /api/orders/cancel-amazon-shipment

Asks Amazon to stop shipping one order it ships by Multi-Channel Fulfillment (the order's AmazonMcf is present). Amazon can stop it only before it starts picking. Needs the OrdersWrite permission.

{
  "OrderId": "6a73...",
  "DryRun": true
}

With DryRun true nothing is sent. A call the real one would refuse is refused the same way.
The real call answers Status: stopped (Amazon had not been sent the order yet), asked (Amazon took the cancel; once it confirms, AmazonMcf is absent and the order is yours to ship or cancel) or queued (MarketplaceHub asks Amazon again within minutes).
A refusal is a 409 whose errors.Reasons is NotSentToAmazon, AlreadyShipped, AlreadyAsked or AmazonRefused (Amazon has started on the order and will ship it).
When your key's writes need approval, the answer is Status: "pending" with a ProposalId.

Which marketplaces these actually reach

Confirm, Cancel and Refund record the change in MarketplaceHub and hand it to the marketplace's own outbound sync. Support is per operation, not per marketplace:

Marketplace	Confirm	Cancel	Refund
Amazon	Yes	Yes	Yes
eBay	Yes	Yes	Yes
Shopify	Yes	Yes	Yes
Walmart	Yes	Yes	Yes
TikTok Shop	Yes	Yes	Yes
BigCommerce	Yes	Whole orders only	Yes
Etsy	Yes	No	No

Etsy's two gaps are permanent, not unfinished. Its Open API is read-only for payments and for the shop ledger — there is no cancel endpoint and no refund endpoint to call, so there is nothing waiting to be built. A tracking record can be created, which is why Confirm works.

Where a push cannot reach, the call still succeeds locally and the response carries a Warnings entry naming the platform and the operation — telling an Etsy caller that "Etsy push-back" is missing would contradict the shipment confirmation that does work. You get one warning per distinct platform, not one per item.

{
  "RequestId": "6a73...",
  "Warnings": [
    "MarketplaceHub cannot send a refund to Etsy, so this change is recorded in MarketplaceHub only and will not reach the marketplace. Apply it in the marketplace's own tools as well."
  ]
}

Check Warnings on every write. It is empty on the happy path, and it is additive — a new reason shows up there rather than as a new kind of failure.

Who is expected to act

Orders are one of the four kinds of data that have an owner (see Source of truth). For orders the owner means who is expected to ship, cancel and refund: MarketplaceHub, or your own system through this API.

It never blocks your call. If MarketplaceHub owns orders and you push a shipment here anyway, the push is applied and a Warnings entry says so. The reverse is also true: if your system owns them, a merchant shipping from the Orders page is told your system was expected to. A push whose owner cannot be resolved costs you the notice, never the push.

Orders the marketplace ships itself

An order the marketplace fulfils itself — Amazon FBA, Walmart Fulfillment Services or Fulfilled by TikTok — cannot be confirmed, cancelled or refunded here, because the marketplace is already doing it. Sending one back would be a second answer to a question the marketplace has answered.

The request is refused whole, with 409 Conflict, naming each line that caused it. This is checked before anything is written, so a marketplace-fulfilled third item cannot leave the first two already confirmed. Only Amazon, Walmart and TikTok Shop report a fulfilment channel; an order from any other marketplace, BigCommerce included, is always treated as one you ship yourself.