Idempotent writes with stored-response replay
Order pre-alerts carry an external order ID; retrying the same creation returns the original result. This is what makes network failures boring instead of expensive.
Guide · Developers
A fulfillment API is judged by its failure modes
Integrating China-leg fulfillment into a storefront, OMS or agent runtime is not a CRUD exercise: a retried request can ship a duplicate parcel, an unverified webhook can corrupt order state, and an estimate mistaken for a bill breaks trust with real money. This guide covers the five properties a production integration needs, using Merchant API V1 (38 operations, 17 MCP tools) as the worked example.
Last updated: 2026-07-27
The five properties that matter
Signed events you can trust and deduplicate
Webhooks are HMAC-SHA256-signed over the raw body, carry immutable event IDs, and are delivered at-least-once. Verify, dedupe, then process — in that order.
Estimates and final quotes as separate objects
The API never lets a pre-measurement estimate masquerade as a bill. The packed quote is produced after measurement and is what settlement reconciles against, line by line.
Ledger-computed inventory
Stock is a fold over immutable movements, not a mutable number. Your reconciliation job can replay the ledger and must land on the same statement the platform produces.
Normalized tracking with re-registration
China-leg events and international carrier events merge into one timeline; when a carrier reissues a tracking number mid-transit, it is re-registered instead of going dark.
A minimal integration checklist
- Store your external order ID with every creation call and treat retries as replays, never as new orders
- Verify webhook HMAC over the raw body before JSON parsing; reject on mismatch; dedupe on event ID
- Model estimate and packed quote as different types in your system, with approval gating dispatch
- Reconcile settlements line-by-line against the packed quote and alert on unexplained lines instead of averaging them away
- For stocked SKUs, sync from the movement ledger, not from point-in-time counters
- Start against a sandbox key after approval; use production only after workflow validation and applicable account terms
Full reference — every operation, parameter, error shape and webhook event — lives in the Merchant API documentation. Store-side WooCommerce integration is covered separately on the plugin page.
Common questions
Why is idempotency non-negotiable for fulfillment APIs?
Because the failure mode is a duplicate physical shipment, not a duplicate database row. A timeout on order creation must be safely retryable: with stored-response replay, the retry returns the original response instead of creating a second order that ships real goods to a real customer.
How should webhook authenticity be verified?
Compute an HMAC-SHA256 over the raw request body with your endpoint secret and compare it to the signature header — before parsing the JSON. Combine that with immutable event IDs and at-least-once delivery semantics: your receiver deduplicates on the event ID, so replays and retries are harmless.
What is the difference between an estimate and the packed quote?
An estimate is computed before goods are measured; the packed quote is generated after packing from real dimensions and weight against the live rate table, and is the number the merchant approves before dispatch. A correct integration never presents an estimate as a final price — the API keeps them as distinct objects.
How do I keep my system’s inventory truthful?
Read inventory that is computed from an immutable stock-movement ledger rather than a mutable counter — the same ledger that produces the monthly statement. Every receive, reserve, dispatch, withdrawal and adjustment is a movement; your integration can re-derive state at any point in time.
How do I get credentials?
Account-first and approval-gated: create a merchant login and submit the integration application in-account. Approval creates and activates the merchant account, then opens sandbox and production key management. There is no public unauthenticated API, and no agent or third party can issue keys on your behalf.
Is there an MCP option instead of raw HTTP?
Yes — a standalone MCP server exposes the supported subset as typed tools for AI agents (estimates, idempotent orders, value-added services, quotes, tracking, settlement, stocking, fulfillment). Same authentication model, same human-approval gates on packed quotes and mixed orders.
Build against the sandbox this week.
Account-first: signup, in-account application, approval, then API-key management.