An API-driven fulfillment operation needs a dependable answer to a simple question: has this instruction already changed the physical work? A timeout does not prove that an order failed. If a store retries after the warehouse accepted the first request, an integration without duplicate protection can create two pick tasks for one purchase.
The architecture below is a proposed design for connecting a store or order-management system to a China warehouse. It does not describe a particular system installed at FulfillNexa.
Separate order receipt from warehouse release
Accepting an order message should create a durable record before triggering physical work. Validate the source account, order reference, SKU mapping, quantity, destination and required delivery data. Return a clear acceptance result or a structured error.
An order awaiting a product decision belongs on hold. It should not disappear from the integration because it cannot yet be picked. Keep the customer-order identity stable through validation, hold resolution and warehouse release.
A useful internal state model distinguishes received, held, released, picking, packed and handed over. Those labels are design choices. Their transition rules, including who may reverse or cancel each state, must be documented for the operation.
Make a retry return the same business result
Assign an idempotency key to an instruction that must take effect once. Store the key with the request’s material fields and processing result. A repeat with the same key and the same content should return the original result rather than create another task.
A repeat using that key with a changed quantity should be rejected or handled as an explicit revision. Silently accepting it makes it impossible to know which version the warehouse followed.
For an illustrative failure, the warehouse accepts order A, records task P and loses the response during a network interruption. The store resends A. The integration finds the recorded instruction and returns P. No second reservation or pick task is created. Retain this record for a period covering the agreed retry and replay process, rather than choosing an arbitrary short expiry.
Protect the message receiver
Authenticate the sender and verify the message using the provider’s documented method. Do not treat a request containing a familiar order number as trustworthy.
Shopify’s webhook verification guidance provides a platform-specific example. The receiving service should also tolerate repeat deliveries and keep processing work separate from the acknowledgement path. Acknowledging a message means it was durably accepted, not necessarily that warehouse work has finished.
Limit the data stored in operational logs. Record identifiers, decisions and error codes while keeping customer details within the approved access controls. A developer should not need a complete customer address to investigate every retry.
Resolve cancellation races explicitly
A cancellation arriving before release can usually stop future work within the agreed process. A cancellation arriving during picking needs an operational response. After carrier handoff, it may require a different exception or return workflow.
Record the cancellation request and its outcome separately. “Cancellation received” must not automatically become “order cancelled.” The warehouse may have already passed the physical stopping point.
Use an atomic state transition or equivalent concurrency control. Two services should not independently approve both a release and a cancellation against the same old order state. Keep the losing action’s result visible to the caller.
Give inventory and fulfillment their own identities
An order can split into several packages or fulfillments. Use stable child identifiers so that one parcel confirmation cannot close every outstanding line by accident. Inventory changes also need their own transaction references.
Shopify’s inventorySetQuantities documentation illustrates why absolute stock updates require comparison controls. An order API should similarly avoid overwriting current quantities with an old snapshot after a delay.
Test recovery before testing maximum speed: replay a message, lose an acknowledgement, cancel during picking and submit an unknown SKU. For each test, reconcile the accepted instruction, reservation, warehouse task and customer-facing status. An integration is dependable when these records still agree after failure, not merely when its normal request returns quickly.
Sources and verification links
Operational rules can change. Check the linked primary sources and confirm shipment-specific requirements before booking.