A shipping integration has to close the loop
A shipping integration is not complete when a label appears. The order has to reach the right fulfilment system, the correct service must be selected, the parcel needs a durable reference and the customer should receive accurate tracking. When something fails, staff need to know what happened without placing the shipment again by guesswork.
At Midoriweb, we treat shipping as an operational workflow. We connect the storefront, order management, warehouse and carrier around clear ownership and visible exceptions. This guide explains what to define before building or replacing that connection, whether you dispatch from your own warehouse, use a fulfilment partner or combine several locations.
If checkout is currently missing a delivery method, start with our shipping methods troubleshooting guide. If a dispatched order has the wrong tracking state, see shipment tracking not updating. The guide below addresses the design of the wider integration rather than one isolated symptom.
Separate checkout promises from dispatch decisions
The delivery option offered at checkout is a promise to the customer. The warehouse may later choose a specific carrier product that fulfils it. Keep those two concepts distinct, and define the mapping between them. A customer selecting next-day delivery should not silently become a standard parcel because a carrier code was missing.
Record the factors that influence eligibility: destination, parcel dimensions, weight, product restrictions, dispatch location and the service agreement. Decide which system evaluates each factor. The checkout may estimate an option using the basket, while the warehouse confirms the final parcel after packing. Any difference needs an agreed business rule.
Also define what happens when the preferred carrier cannot provide the service. Should staff review the order, use an approved alternative or contact the customer? The integration should implement that decision. It should not invent a delivery promise or choose the cheapest available service without instruction.
Map the complete journey and its owners
Start with one ordinary order and follow it through payment confirmation, fulfilment release, picking, packing, label creation, dispatch and customer notification. At each step, identify the system that owns the state and the reference passed to the next system.
A Magento order number, warehouse order reference, shipment reference and carrier tracking number can all describe related objects without being interchangeable. Preserve their relationships. Staff should be able to find a carrier response from the relevant shipment without searching through an entire day's logs.
The ecommerce integration planning guide provides a broader ownership framework. For shipping, pay particular attention to the distinction between requesting a label, receiving a label and confirming physical dispatch. Those events do not necessarily happen together.
- 01ReleaseApproved order to fulfilment
- 02CreateParcel and label references
- 03ConfirmPhysical dispatch and tracking
- 04ReconcileResolve unknown or failed outcomes
Worked example: one order, two parcels
Imagine a fictional order containing a lamp and a replacement shade. The warehouse packs them separately because one item is fragile. The order is still one commercial transaction, but fulfilment now contains two parcels with their own tracking references.
The integration must preserve which items and quantities belong to each shipment. If one parcel leaves today and the other tomorrow, the customer should not be told that the whole order has been dispatched after the first label is created. If the second label request fails, staff need an exception attached to that parcel rather than an ambiguous order-level error.
Now consider a lost response. The carrier creates the second label, but the connection drops before the warehouse receives confirmation. Repeating the same request blindly could create another label and another charge. The recovery process needs to reconcile the original request with the carrier's state before creating anything new. The exact mechanism depends on the carrier API and its supported references.
| Event | Expected response |
|---|---|
| Label accepted | Save the carrier reference against the correct parcel. |
| Response lost | Reconcile the original operation before creating another label. |
| Partial dispatch | Notify only the items and quantities actually dispatched. |
| Invalid address | Expose a correction task; do not endlessly retry unchanged data. |
| Carrier unavailable | Apply the agreed fallback or hold for review. |
Design retries around business consequences
Some failures are safe to retry automatically. Others require a lookup or human decision first. Distinguish a request rejected before processing from a timeout where the remote outcome is unknown. A timeout means confirmation is missing; it does not prove the shipment was never created.
Where supported, use the provider's idempotency or merchant-reference mechanism to identify the same operation. Keep a durable local record of the operation and its outcome. Where a provider lacks such a mechanism, define a reconciliation step rather than claiming that duplicate prevention is guaranteed.
Retry with limits, record the reason and escalate persistent failures. A queue that continually resubmits an invalid address is not recovering. It is hiding an unresolved business exception. Staff should see what needs correcting, which shipment is affected and whether any label already exists.
Give operations a useful exception queue
An exception queue should group work by the action needed. An invalid postcode requires different handling from a carrier outage or a missing product weight. Include a clear status, the relevant order or shipment reference, the last attempt and the next permitted action.
Do not fill routine dashboards or logs with unnecessary customer data. Show staff enough information to resolve the issue through the appropriate access-controlled system. Keep credentials and complete provider payloads out of ordinary customer messages.
Define responsibility as well as visibility. Who checks unresolved shipments before the daily dispatch cut-off? Who handles a carrier incident? Who can approve a service substitution? A well-built integration still needs a business owner for decisions that software cannot make safely on its own.
Test the exceptions that happen on a working day
Test a valid order, an unsupported destination, a missing required field, a partial shipment, a repeated callback and a lost response. Include cancellation before and after label creation, because the provider's rules may differ at those points. Confirm how unused labels are handled under the actual carrier agreement.
Use provider-supported test facilities where available, with clearly identified test orders. Verify that tests cannot trigger real dispatch, customer notifications or unintended charges. When a provider cannot reproduce a particular failure in its test environment, record the limitation and agree a controlled verification method.
Check the customer-facing result as well as the API response. Can the customer understand which items have shipped? Does the tracking link resolve to the correct carrier? Does a repeated notification create confusion? Technical success should match the operational outcome.
Launch with reconciliation and a fallback
Before switching over, agree how existing unfulfilled orders will be handled. Avoid having two integrations compete to create shipments for the same order. Record a cut-over boundary and decide which system owns work already in progress.
Compare the counts and references at each stage after launch: released orders, created shipments, accepted labels and dispatch confirmations. Explain differences rather than expecting every count to match when partial shipments are valid. Keep a documented manual process for urgent exceptions, including how manual work is reconciled back into the system.
If you need a new connection or a more reliable handover between systems, our ecommerce integrations service can help define and implement the workflow. Bring the current process, provider details and a few representative exceptions. The most useful starting point is usually the place where staff have to stop and work around the software.