Orders

This guide covers working with orders through the API: receiving them, reading them correctly, acting on them in the right state, and keeping your system and the Platform in agreement about what was sold. Most integrations do not create orders: buyers create orders by checking out on the Platform: so this guide is chiefly about the receiving side: the orders placed with your account, line by line, and what you do next. Endpoint detail is in Orders Endpoints; how products get into the catalog behind those orders is in Catalog.

Goal and prerequisites

Goal: every order placed with your account reaches your systems promptly, is understood exactly as the buyer placed it, and is acted on: fulfilled, cancelled, or returned: in the state the order is actually in.

Prerequisites: an API key with orders scope, and a subscription to order events (Webhooks) or a polling process with a tracked high-water mark. Event-driven receipt is the standard; polling is the fallback and the reconciliation tool.

The order lifecycle

An order moves through a small set of states, and every defect in order handling comes from acting in the wrong one

1. Placed: the buyer checked out. The order exists; treat its contents as fixed from this moment.
2. Payment pending: payment has not been confirmed. Nothing ships, and nothing counts as revenue, in this state.
3. Paid: the Platform has confirmed payment through its payment processing. Only the Platform's confirmation moves an order here; a buyer's claim, a redirect back from a payment page, or a screenshot is not a payment signal.
4. In fulfillment: the order is being prepared and shipped; see Fulfillment.
5. Complete: every line is delivered or otherwise resolved.
6. Cancelled: the order was stopped before fulfillment; any payment taken is refunded.
7. In return: some or all lines are coming back; see Returns.

Guard every action by state: do not fulfill an order that is not paid, do not refund a line that was never paid, and do not cancel an order that has already shipped: each transition the API permits is listed in Orders Endpoints, and Data Types and Enums defines the status values.

Receiving orders

By webhook (standard). Register for order events as Webhooks describes and Webhook Event Schemas defines. On an order-placed or order-paid event, fetch the full order by its id and store it in your system keyed by that id. Handle delivery idempotently: events are delivered at least once, and your receiver must make a second delivery a no-op.

By polling (fallback and reconciliation). Walk the orders collection with cursor pagination (Pagination and Filtering (Pagination & Filtering)), filtered to orders created or updated since your high-water mark, and advance the mark only after the walk completes. Poll on a measured cadence inside your rate budget (Rate Limit Headers); if you are polling faster than your orders arrive, you should be on webhooks.

Reading an order

• Line items are the record. Each line carries the product, the variant, the quantity, and the price as charged. Prices and names on the line are the values at purchase time and are the values to display, invoice, and reconcile against: never the catalog's current values, which may have changed since.
• Money is a decimal string with a currency (Overview). Sum lines in decimal arithmetic in your own system; never in floating point.
• Addresses are supplied as structured fields on the order. Use them exactly as given for fulfillment; if an address cannot be used as given, stop and resolve it with the buyer through the Platform rather than guessing: a shipment sent to a guessed address is a loss and a support case.
• Buyer details are provided for fulfilling the order and communicating about it. Use them for those purposes only; retention and use limits are in API Policies and the Data Use, Retention and Deletion policy.

Multi-party orders

A single buyer checkout can span several accounts. When it does, your account sees its own portion: your lines, your fulfillment duty, your share of the order's value. The order is not complete until every portion resolves, but your obligations attach to your portion: fulfill your lines, report your shipments, and handle your returns without waiting on portions that are not yours.

Acting on orders

• Acknowledge promptly. Your systems should register a new paid order within minutes, so fulfillment starts inside the service levels your account is measured against.
• Cancel only in the states that allow it, through the API, with the reason the API asks for. A cancellation you make in your own system but never send to the Platform does not exist for the buyer.
• Update through the order's own transitions, never by editing fields to mimic a state. If the API rejects a transition, the order is telling you its real state: re-read it rather than forcing yours.
• Send every write with an Idempotency-Key(Idempotency Keys). Retried cancellations and retried updates must land once.

Failure handling

• An event arrived but the order fetch returns 404: confirm you are fetching under the account the event belongs to; ids resolve only within their account's scope. Then re-read after a short delay before escalating.
• Your records and the Platform disagree about an order's state: the Platform's order is the record of the sale. Re-read the order, adopt its state, and find why your copy drifted (a missed event is the usual cause; reconciliation polling exists for exactly this).
• Duplicate orders in your system: you processed the same event or the same order twice under different local keys. Merge to the Platform id as the single key.
• An order is stuck payment pending: payment has not been confirmed; do not fulfill it, and do not chase the buyer for payment outside the Platform. Orders that never confirm expire on the Platform's side.

What good looks like

Orders arrive by webhook and are fetched once, stored by Platform id, and reconciled by a slow poll that finds nothing new. State guards are checked before every action, line items are invoiced as charged, and a cancelled or returned order in your system always matches the Platform's record. When support asks "what happened to this order," your system and the Platform give the same answer.