Migrating Shopify tracking numbers when the singular field overrides the array
Adding the plural tracking field is insufficient if the old singular field remains in the request.
Inspect the old field before adding the new one
When singular and plural tracking fields are both supplied, the singular field takes precedence. Remove the old mapping before relying on the full list for a multi-package order. An imported order can be created successfully while retaining only one of the source system's two package references. Successful order counts do not establish complete tracking information for the customer. [1, 2, 3]
An omission explained by documented precedence
Shopify's 2026-08-03 announcement introduces the trackingNumbers array on OrderCreateFulfillmentInput for 2026-10. If trackingNumber and trackingNumbers are both provided, the singular value is used and the array is ignored. trackingCompany applies to every number in that array. Combining different carriers and conflicting singular/plural fields are consequently separate checks. [1]
Compare the source and result at package scope
The import owner should compare the source package tracking set with the created result. If a number is missing, correct any request mapping that still supplies the singular field and check the affected order again. Fix the comparison to the same fulfillment within the same order. Preserve both the source list and transmitted payload to distinguish extraction errors from request-construction conflicts. [1, 3]
A failing fixture loses one of two references
Define illustrative source package references PKG-A and PKG-B, giving the expected set PKG-A|PKG-B. A result containing both passes the preservation condition. A result with only PKG-A loses tracking information for PKG-B even though the order count is unchanged. Compare the complete values as well as their count, since a different reference can preserve cardinality. The vertical bar is only a readable fixture notation; production normalization must avoid delimiter collisions. [1, 3]
Preservation is not delivery confirmation
ColumnPairValidator in Truthound Core 3.3.2 can compare externally normalized expected and observed sets. It skips null pairs, so check input presence separately. The result supports reference preservation, not reference authenticity or delivery completion. Retire the singular field in the request generator or investigate the documented fulfillment-update path. This example is not evidence that an order was actually created or modified. [1, 2, 3]
Application conditions
For order imports in 2026-10 or later, establish the source package list first. Compare complete nonmissing sets within the same fulfillment and carrier scope.
Alternatives
Explicitly retire the singular field in the request generator. When needed, handle missing references through the documented fulfillment-update path.
Limitations
Tracking-set equality does not establish delivery completion. trackingCompany applies to the entire array; do not arbitrarily combine packages handled by different carriers.
Evidence
- Event checked
- Subject checked
- Modified
