The client's problem
We are experiencing a persistent issue with our Shopify-ShipStation integration where orders are not consistently updating to "Fulfilled" status after processing.
My analysis
1
The cause: natureslab.com/pages/international
2
For international shipping, USPS delivers a package only to a hub in the destination country and then transfers it to a local carrier (e.g., Royal Mail in the United Kingdom) for further delivery.
3
National postal services (including USPS and Royal Mail) identify international shipments using the Universal Postal Union's «UPU S10» standard.
Example: «LZ123456789US» (usually printed with spaces on shipping labels: «LZ 12345678 9 US»).
By the way, private carriers (FedEx, UPS, DHL) do not use «UPU S10» and instead use their own tracking ID formats for international shipments.
4
When ShipStation notifies Shopify about a package status change, it specifies the tracking ID of the package: tracking_number.
- docs.shipstation.com/apis/shipengine/docs/tracking/webhooks#sample-track-webhook-payload
- shipengine.com/docs/tracking/webhooks/#sample-track-webhook-payload
5
Shopify validates the tracking ID format against the rules associated with the carrier specified in the notification.
6
For domestic shipments, USPS uses the «IMpb» format for tracking IDs.
7
If ShipStation specifies USPS as the carrier, Shopify expects the tracking ID in the «IMpb» format.
Having received a tracking ID in the «UPU S10» format instead, Shopify recognizes it as invalid and rejects the ShipStation notification, returning the HTTP status code 422 («Unprocessable Content»).
Due to this rejection, the order's fulfillment status in Shopify does not update to «Fulfilled».