Overview
When a Shopify order ships in more than one box — each with its own carrier tracking number — Luminous creates a separate Shopify fulfillment for every unique tracking number. Each fulfillment contains only the order lines that were physically in that group of packages. Shopify then sends the customer a tracking notification for each box individually.
This feature is controlled by the Package-Aware Fulfillment Push setting. It must be enabled on your account for the behavior described below to apply.
How it works, step by step
1. Luminous receives shipment and package data
When your warehouse or shipping integration (such as ShipStation or a 3PL) reports a shipment, it can include individual package records, each carrying its own tracking number and the specific items packed inside.
2. Luminous checks for multiple distinct tracking numbers
Before pushing to Shopify, Luminous inspects the package records attached to the shipment. It collects all non-empty tracking numbers and checks whether more than one distinct tracking number exists.
- If all packages share the same tracking number (or there is only one), Luminous pushes a single standard fulfillment — no change from the normal flow.
- If two or more packages carry different tracking numbers, Luminous switches to the multi-package path.
3. Packages are grouped by tracking number
Each package is sorted into a group based on its tracking number. Packages that have no tracking number are collected into a fallback group that uses the shipment's overall tracking number.
4. One Shopify fulfillment is created per tracking group
For each group, Luminous:
- Builds a fulfillment payload that contains only the order line items found in that group's packages.
- Matches each line item back to the original Shopify order using the Shopify line-item identifier that was captured when the order was first imported.
- Posts the payload to Shopify as a new fulfillment record, with the group's tracking number attached.
If a group ends up with no valid line items (for example, because a package item couldn't be matched to an order line), that group is skipped and a warning is logged.
5. Shopify reflects multiple fulfillments
After all groups are processed, the original Shopify order will show multiple fulfillment records — one per tracking number. Each fulfillment lists only the items shipped in that box, and Shopify emails the customer a tracking notification for each one.
What the customer sees on Shopify
- The order moves to Fulfilled once all line items are covered.
- Each fulfillment has its own tracking number and (where supported) a direct tracking link to the carrier.
- If the order was partially shipped across boxes and some items are still pending, those items remain Unfulfilled until a subsequent shipment is pushed.
Edge cases to be aware of
| Situation | What happens |
|---|---|
| All packages have the same tracking number | Treated as a single-package shipment; one fulfillment is created |
| Some packages have no tracking number | Those packages are grouped with the shipment's overall tracking number |
| A package's items can't be matched to a Shopify order line | That package's items are skipped for that push |
| All tracking groups fail to push | The shipment is marked as a failed push and the error is recorded for review |
Frequently asked questions
Does this work for all sales channels, or only Shopify? The package-aware push routes through the same fulfillment processor used for all integrated channels. Whether a given channel (Walmart, etc.) supports receiving multiple separate fulfillment updates depends on that channel's own API. Shopify fully supports it.
What if I need to manually re-push tracking after a failed multi-package push? Use the "Force push to source…" feature (available from the order detail view). See the related article for step-by-step instructions.
Is there anything I need to configure? The Package-Aware Fulfillment Push capability is a feature flag that must be enabled by the Luminous team for your account. If you believe your account should have it enabled and orders are only receiving a single tracking number on Shopify, contact Luminous support.