Fulfillment

This guide covers the work between "paid" and "delivered": taking a paid order, confirming you can ship it, reporting shipments with tracking, and handling the exceptions: partial shipments, rejected lines, lost parcels: as first-class flows rather than surprises. Endpoint detail is in Fulfillment Endpoints. The states an order moves through are defined in Orders; the stock discipline that precedes shipment is in Inventory.

Goal and prerequisites

Goal: no paid order is ever in an unknown state. Every order is queued, confirmed, shipped, delivered, or in a named exception with a next step: and the buyer can see the same state you see.

Prerequisites: orders arriving reliably in your systems (Orders), inventory revalidation against your live stock (Inventory), and a shipment-reporting step in your packing process that runs for every parcel, without exception.

Step 1: Take the paid order

Fulfillment begins when an order reaches paid state: not when a buyer says they paid, and not before. Work the queue in order of payment time

1. Read the order in full (Orders Endpoints): lines, quantities, ship-to address as given.
2. Revalidate stock against your live inventory for every line. If a line cannot ship, go to the exception path (below) now, before money and time are committed elsewhere.
3. Confirm acceptance in your own system. From this point the service-level clock your account is measured against is running.

Step 2: Ship and report

Reporting the shipment is part of shipping, not paperwork after it

1. Pack and label the parcel. Buy labels with the address exactly as the order states it; if the address cannot be used as given, stop and resolve it through the Platform: never ship to a corrected-by-guess address.
2. Report the shipment through Fulfillment Endpoints at the moment the carrier takes the parcel: the order, the lines in this parcel, the carrier, and the tracking number.
3. Send the report with an Idempotency-Key (Idempotency Keys). A retried report must update the same shipment, never create a second one: and never buy or report a second label for a parcel that already has one, unless you are deliberately replacing it and say so in the call the API provides for that purpose.

Tracking accuracy is a trust surface: a tracking number reported late, mistyped, or before the parcel exists reads to the buyer as a seller who did not ship.

Step 3: Follow the parcel to delivery

The Platform tracks the shipment from the tracking number you reported and reflects its state to the buyer. Your jobs after reporting

• Watch for stalls. A shipment with no carrier movement inside the expected window is an exception: check with the carrier, then tell the buyer honestly what is happening before they ask.
• Keep multi-parcel orders straight. Report each parcel against the lines it contains. The order completes when every line is delivered or resolved: not when the first parcel ships. Show and report state per shipment: "two of three items shipped" is honest; "your order has shipped" when one item has not is a support case.

Exception paths

Design for these first; they are most of the work

• A line cannot be fulfilled (discontinued, damaged stock, undeliverable address): cancel the line or the order through the API at once, so the refund starts and the buyer is told what happened and what happens next. Do not let an unfillable line sit in the queue aging.
• Partial shipment: ship what can ship, keep the remainder open with its own expected shipment, and complete the order only when every line resolves.
• Lost parcel: start the carrier's investigation, but do not make the buyer wait for its paperwork: replace or refund under the Platform's policies while the investigation runs.
• Carrier or address failure after dispatch: the parcel's state changes; keep the buyer informed through the order, and resolve to delivery, return-to-you, or refund: a shipment is never left in limbo.

Record every exception on the order with its timestamp and its outcome. "What happened to my order" is the most common support question, and the answer should be in the record, not in someone's memory.

Service levels

How fast orders must be confirmed, shipped, and delivered is set by the Service Level Requirements for your account type, and performance against those levels feeds your account standing (Governance). The integration's part is mechanical: prompt order intake, same-day shipment reporting, and exception handling that starts when the exception is discovered: not when the buyer complains.

Failure handling

• Shipment report rejected: read the error code (Error Codes): most often the order is not in a state that accepts a shipment (not yet paid, already complete, already cancelled) or the lines listed do not match the order. Re-read the order, correct the report, and send it again with the same idempotency key.
• 429: you are reporting in bursts faster than your tier allows; queue reports and send at a steady rate (Rate Limit Headers). A shipment report delayed minutes by your own queue is still timely; one lost to an error storm is not.
• Tracking reported but the carrier shows nothing: you reported before handover, or mistyped the number. Verify against the carrier, correct the report through the API if it is wrong, and treat the cause as a packing-process defect to fix.

What to build

• If you run a warehouse: the queue is paid-and-unshipped orders; the actions are confirm, ship-and-report, and exception: every action timestamped, every parcel tracked.
• If you build buyer-facing views: read fulfillment state from the API per shipment and show it as the Platform reports it; never summarize several shipments into a claim the slowest one makes false.