Shipments & Receiving
How to create shipments against a PO and record goods receipt, including how received quantities are synced back to Shopify inventory.
Shipment Statuses
| Status | Meaning |
|---|---|
| announced | Shipment created; goods not yet received |
| received | Goods received and inventory updated |
| cancelled | Shipment voided; any synced incoming stock reversed automatically |
Creating a Shipment
Shipments can be added from the Shipments tab on the PO details page, or the Add shipment modal opens automatically after a PO is confirmed.
Each shipment requires:
| Field | Required? | Notes |
|---|---|---|
| Reference | ✅ Required | The only mandatory field on a shipment |
| Estimated delivery date | Optional | |
| Delivery location | Optional | Shopify location |
| Shipping cost | Optional | Used in landed cost calculation |
| Shipment items | — | Per line item: set quantity announced |
| Shipments can only be created for line items that have unannounced pending | ||
quantity (quantityOrdered > quantityAnnouncedComputed). Synplex pre-fills | ||
| each shipment item with the remaining pending quantity. |
PO status transition: when the first shipment is created against a confirmed PO, the PO status automatically changes from confirmed to in_transit. This happens in the backend and requires no manual action. Subsequent shipments against the same PO do not change the status again.
Receiving a Shipment
Open the shipment from the Shipments tab. For each shipment item, enter:
| Field | Description |
|---|---|
| Quantity announced | Units expected in this shipment |
| Quantity accepted | Units that arrived and passed inspection |
| Quantity defect | Units that arrived but failed inspection |
| These three quantities are tracked independently. Synplex syncs each one to | |
| Shopify as a separate inventory mutation: |
- Quantity announced → adjusts Shopify's incoming stock bucket
- Quantity accepted → moves stock from incoming → available
- Quantity defect → moves stock from incoming → damaged
Syncing happens per field change, not on a single save action. Every time you update a quantity on a shipment item, Synplex immediately computes the delta versus what was previously synced and enqueues the corresponding Shopify inventory mutation. Changes are only processed if Sync receipts to Shopify is enabled on the PO and the shipment item has a valid inventory level linked.
How the Shopify Sync Works
Synplex uses a delta-based, debounced batch sync to push inventory changes to Shopify. Understanding this avoids confusion when changes don't appear in Shopify instantly.
Delta tracking
Each shipment item stores three "last synced" baseline values:
syncedQuantityAnnounced, syncedQuantityAccepted, syncedQuantityDefect.
On every update, Synplex computes the delta between the new value and the
baseline. Only non-zero deltas result in a Shopify API call.
Batch queue
After each shipment item update, Synplex enqueues the syncPOToShopify
background action with a 5-second deduplication window. If multiple
items in the same shipment are updated within 5 seconds, they are batched
into a single Shopify API call. The queue runs serially per shop
(maxConcurrency: 1) to avoid Shopify rate limit errors.
Retry behaviour
The batch sync job retries up to 3 times with exponential backoff (1 min → 2 min → 4 min, with jitter) if the Shopify API call fails.
Sync log
Every sync attempt — including skipped, pending, and failed ones — is
recorded as a poInventorySyncLog entry linked to the shipment. You can
inspect these logs to diagnose any sync issues.
Preflight guard
If a shipment item's PO line item has no inventory level linked, the sync is skipped and a SKIPPED log entry is created. No Shopify mutation is made. This typically happens when a product was added to a PO without a warehouse location, or the location has no inventory level record in Synplex.
Partial Receipts
If only part of a shipment arrives, enter the actual quantities for the units that did arrive and leave the rest. The remaining quantity stays open on the PO. You can add further shipments against the same PO until fully received. The PO status remains in_transit while announced shipments have outstanding undelivered quantity.
Handling Discrepancies
Quantity delivered < quantity announced
Update the shipment item to reflect the actual quantity. The shortfall remains as pending quantity on the PO line item. Create a new shipment for the outstanding quantity when the supplier dispatches the remainder.
Quantity accepted < quantity delivered
Set quantity accepted to the good units only and quantity defect to the failed units. Only accepted quantity moves to available inventory; defect quantity moves to the damaged bucket. Raise a claim with the supplier for the rejected units.
Wrong product received
Do not receive the shipment in Synplex until the correct goods arrive. Receiving incorrect stock will immediately corrupt your on-hand inventory counts and trigger incorrect stock status recalculations.
Cancelling a Shipment
If a shipment is cancelled after quantities have already been synced to Shopify, Synplex automatically runs a cancellation compensation: it computes the net incoming stock that was previously synced (announced minus accepted minus defect) and enqueues a negative adjustment to reverse it in Shopify. This only runs if Sync receipts to Shopify is enabled on the PO.
Shopify Inventory Sync Toggle
Each PO has a Sync receipts to Shopify toggle that controls all of the above sync behaviour.
- Shop-level default: set in Settings → Sync PO receipts to Shopify by default. When a new PO is created and the toggle is not explicitly set, the backend reads the shop's setting and applies it automatically.
- Per-PO override: the toggle can be changed on any individual PO, but only while the PO is in draft status. Once the PO is confirmed it is locked.
- Sync log: every sync attempt is recorded as a
poInventorySyncLogentry, visible on the shipment record.
Multi-Location Shipments
A single PO can have multiple shipments, each assigned to a different Shopify location. Each shipment tracks its own quantities independently. The PO detail page shows aggregate totals (ordered / delivered / accepted / announced) across all shipments.