Receive and ship orders

On Path B, the orders and both subscriptions, your platform fulfills Snapcaster orders in its own system. Snapcaster handles checkout and payment, then sends your platform one order per seller.

Build these calls and notifications in this order.

1. Validate each seller’s key with GET /me and store its sellerId.
2. Push listings with POST /listings or POST /listings/bulk, and remove them with DELETE /listings.
3. Receive order.created, and with both also inventory.adjusted, and move stock by the rules in Stock change for each event.
4. Push a newer listing snapshot after that 2xx to release the hold on sold units.
5. With PATCH /orders/{orderId}/fulfillment, optionally report accepted, then report shipped with tracking before dispatch.deadline_at.
6. Answer order.cancellation_request.created with POST /orders/{orderId}/cancel or POST /orders/{orderId}/cancellation-requests/{requestId}/decline, and order.change_request.created with POST /orders/{orderId}/change-requests/{requestId}/accept or POST /orders/{orderId}/change-requests/{requestId}/decline.
7. File a fulfillment report with POST /orders/{orderId}/change-requests when lines cannot ship as sold.
8. Cancel before shipping with POST /orders/{orderId}/cancel and refund after it with POST /orders/{orderId}/refunds.
9. Receive order.updated, order.cancelled, and order.refunded, including for the cancellations and refunds you requested.
10. Recover missed events with GET /orders and its syncToken, and read one order with GET /orders/{orderId}.

Steps 1 to 5 and 10 are on this page, steps 6 to 8 are in Cancel orders and answer requests, and step 9 is in Handle order updates.

order.created carries the order in data: the buyer’s name, email and shipping address in customer, the line snapshots, external_ref, shipping, and tax, with money in integer cents.

Every line carries line_ref, which identifies the purchase, and sku_id, which identifies the card. One order can hold two lines with the same sku_id, bought at different times and prices, so key your records on line_ref.

order.created carries the purchase as the buyer made it at checkout, and every retry repeats the same payload bytes, with one exception.

If Snapcaster corrects a guest buyer’s mistyped email, it sends no event for the correction. Every later delivery of order.created and order.updated carries the corrected customer.email, and nothing else in their bytes changes. Polling returns the corrected email too.

Expect duplicate deliveries and events that arrive out of order, and reconcile events for the same order by the order id in data.

Register your webhook endpoint before you take orders. Your 2xx on the event that announced a sale is what acknowledges its stock, so while no endpoint is registered or deliveries fail, the sold units stay held and your listings show less stock than you have. Release the hold on sold units and the retry schedule cover both.

GET /orders and GET /orders/{orderId} return the complete current order, so polling recovers an order’s state after a missed webhook. It does not recover what the event carried, such as the purchase as the buyer made it at checkout or an order.updated reason, and it acknowledges nothing.

Run each polling pass in these steps:

1. On your first pass, send GET /orders with no query parameters to get every order of the seller. To start later, send since instead, and Snapcaster returns the orders that changed at or after that time. On every later pass, send syncToken with the token your previous pass saved.
2. While the response’s nextCursor is not null, send GET /orders with cursor set to it, and with no syncToken or since. Any request can also send limit, up to 1,000 orders a page, and a request without it gets 100.
3. Store each order in the page by order_id, and replace any copy you hold.
4. When a page has nextCursor: null, it carries syncToken. Save that token in the same write as the orders you stored, and send it on the next pass.

An order appears at most once in a pass, and the copy from the latest pass is current. The token makes the next pass include transactions that committed late, so never replace it with your wall clock or the largest updated_at you saw. A token never expires and works only for the seller whose key created it. A malformed token, or one from another seller, returns HTTP 400 INVALID_REQUEST.

Purchase totals stay at the checkout amounts, and each cancellation and refund in the order’s history reports its own payment_refund, which is null when Snapcaster has no payment information for it, such as on an order without a payment. Reconcile history lines on line_ref, never on sku_id. line_ref is null only on an older cancellation line that no Snapcaster record ties to a single purchase.

Send status updates to PATCH /orders/{orderId}/fulfillment. Reporting accepted is optional, because shipped implies it.

{
  "status": "accepted"
}

An order with shipping.is_tracked: true ships with trackingCompany, trackingNumber, and an optional trackingUrl. An untracked order ships with no tracking fields. trackingCompany is the carrier’s name as the buyer should read it, such as Canada Post, and Snapcaster shows the buyer your values as you sent them. The buyer’s order page links trackingUrl only when it is an HTTPS URL on a Canada Post, Purolator, UPS, FedEx, or DHL domain.

Address verification never blocks shipping, whatever address_verification.status reads. Ship to ship_to, and act on a problem verdict before you ship by following Address changes. The response is the updated order, with your tracking in fulfillment and the ship time in dispatch.dispatched_at. An order that already reads shipped was reported by an earlier request or by the seller in the dashboard. Reporting delivered after shipping is optional, and Snapcaster sends no webhook for fulfillment you report.

Ship each order by its deadline_at, the end of the third Toronto business day after the order was placed, not counting weekends and federal statutory holidays. An order still unshipped at the deadline goes overdue. Snapcaster sets dispatch.overdue_at, pauses the seller payout for the order, and sends order.dispatch_overdue once. Shipping late does not lift the pause, so ship, report tracking, and have the seller contact Snapcaster support to release the payout. A missed overdue event shows up in your next syncToken poll with dispatch.overdue_at set. Snapcaster marks orders overdue only in production, so in the sandbox you can read dispatch.overdue_at and dispatch.payout_paused but never receive order.dispatch_overdue.

The fulfillment request takes only status and the tracking fields, and naming lines returns HTTP 400 INVALID_REQUEST. To remove or substitute lines that cannot ship as sold, file a fulfillment report. To cancel before shipping or refund after, see Cancel or refund an order.

Every order operation that is not a GET requires these headers.

Choose a new UUID Idempotency-Key for each command, and if a response is lost, resend with the same key, order, operation, and body. Calls with an Idempotency-Key says what the replay returns.

Cancellations, buyer requests and order updates have their own pages.

• Answer change requests from buyers.
• File fulfillment reports when lines cannot ship as sold.
• Handle order updates, covering address changes, substituted lines, substitution credits, and payment refund outcomes.