How the Order sync works
Once the Carriyo Shopify App is installed, orders move between the two systems on their own. This page explains what each system controls, what changes travel in which direction, and why a few actions in Carriyo are turned off for Shopify orders.
Read it when you want to predict what will happen after you change something, in either system.
How the two systems line up
Carriyo and Shopify describe an order in almost the same way. Both use the same three ideas, under the same names.
| In Shopify | In Carriyo | What it holds |
|---|---|---|
| Order | Order | The purchase: customer, address, items, prices, payment |
| Fulfillment order | Fulfillment order | A set of items to be sent from one location |
| Fulfillment | Fulfillment | A record that items have been dispatched |
Because the two line up so closely, most of the sync is a straight copy. A fulfillment order in Shopify is the same fulfillment order in Carriyo, holding the same items and pointing at the same location.
One thing exists only in Carriyo: the shipment. In Shopify, dispatching goods is a fulfillment with a tracking number typed onto it, and that is the whole picture. Carriyo adds the delivery layer underneath it:
- picking a carrier using your rules
- booking the consignment
- generating the label and paperwork
- tracking the parcel through to delivery
That split gives you a rule that predicts nearly everything on this page:
Shopify is the source of truth for the order itself. Carriyo is the source of truth for how it gets delivered. Carriyo sends Shopify a summary of delivery progress, because a tracking number and a status are all Shopify can hold.
What flows from Shopify to Carriyo
| When this happens in Shopify | Carriyo does this |
|---|---|
| A customer places an order | Creates the matching order, with its fulfillment orders |
| Someone edits the order | Updates the Carriyo copy to match |
| The order is cancelled | Cancels the Carriyo order and maps the cancellation reason |
| Items are fulfilled in Shopify | Records the fulfillment, and creates a shipment if Create Shipment on Fulfillment is on |
| A fulfillment is cancelled | Reverses it in Carriyo and returns the items to open |
| A fulfillment order is split, merged, or moved | Applies the same change to the Carriyo fulfillment orders |
Carriyo reads the current state from Shopify before it acts, rather than trusting the notification alone. That keeps the two copies aligned even when several changes land close together.
Order edits
Carriyo compares the incoming order against the copy it already holds and applies what actually changed. If an edit in Shopify does not change anything Carriyo tracks, nothing is written, and no new activity appears on the order.
Two situations are handled deliberately:
- Fulfilled items are protected. If part of the order has already been dispatched, Carriyo does not rewrite that part.
- Late notifications are ignored. If a notification arrives describing an older version of the order than Carriyo already holds, Carriyo keeps the newer one.
What flows from Carriyo to Shopify
| When this happens in Carriyo | Shopify is updated with |
|---|---|
| You fulfill items | A new fulfillment on the matching fulfillment order |
| You reverse a fulfillment | The fulfillment is cancelled |
| A shipment is booked | The tracking number and tracking link |
| A shipment moves through the carrier network | The delivery status on the fulfillment |
| You split or merge a fulfillment order | The same change, applied in Shopify |
| You change a fulfillment order's location | The fulfillment order is moved, if Shopify accepts it |
| You cancel the order | The order is cancelled, with the reason mapped across |
For how Carriyo shipment statuses appear on the Shopify order, see the status table on the Shopify connector page.
Changing the fulfillment location
When you change the fulfillment location on a Carriyo fulfillment order, Carriyo asks Shopify to move the matching fulfillment order to that location. Shopify decides whether the move is allowed, and it checks its own stock settings first.
Shopify only moves items to a location that is set to stock them. Before you change the location, make sure every product on that fulfillment order is stocked at the destination location in Shopify.
If none of them are, Shopify refuses the move and replies "None of the items are stocked at the new location." The location then changes in Carriyo but stays as it was in Shopify, and the two sides show different locations.
What Shopify does depends on what it finds at the destination:
| At the destination | What happens |
|---|---|
| Every item is stocked there | The fulfillment order moves. Both sides match |
| Only some items are stocked there | Shopify moves those and leaves the rest on a separate fulfillment order. Carriyo keeps them together, so the two sides no longer match |
| No items are stocked there | Shopify refuses the move. Carriyo shows the new location, Shopify keeps the old one |
Only the first row leaves the two systems in step, which is why the all-items check matters before you move anything.
Delivery updates Carriyo does not send
- Pre-booked shipments. When the carrier was arranged outside Carriyo, Carriyo is not the authority on that shipment. It leaves the Shopify fulfillment alone rather than overwriting details you already have.
- Draft shipments. Nothing is sent until the shipment is real. A shipment in draft has no tracking number to share.
- Digital fulfillment orders. Nothing physical ships, so there is nothing to track.
What Carriyo never changes in Shopify
Carriyo does not write back to the commercial side of the order. That means:
- items and quantities
- prices, discounts, and taxes
- the customer record
- billing and delivery addresses
These belong to Shopify. Your Shopify order stays the record your finance and customer service teams work from, and Carriyo never edits it behind you.
Actions not available on Shopify orders
Some actions you would normally have in Carriyo are turned off for orders that came from Shopify. In every case the reason is the same: Carriyo will not make a change it cannot reflect back in Shopify, because that would leave the two systems disagreeing with no way to reconcile them.
| Action | Why it is turned off |
|---|---|
| Put an order or fulfillment order on hold | Shopify has no equivalent state, so the hold could never appear there |
| Edit the order contents, prices, or addresses | Shopify is the source of truth for these. Make the change in Shopify and it flows through |
| Cancel a single fulfillment order | Cancel the whole order instead, which Carriyo can mirror |
| Split a fulfillment order after part of it has shipped | Shopify has already restructured the order at that point |
| Import an order that already came from Shopify | It is already synced. The row is skipped during import |
Cancelling the whole order, allocating stock, splitting a fulfillment order before anything ships, changing its location, fulfilling, and booking carriers all work normally on Shopify orders. So does every Carriyo delivery feature: carrier selection rules, labels, and tracking.
If an automatic hold rule would otherwise apply to a Shopify order, it is skipped for the same reason. Set up the equivalent control in Shopify if you need it.
Settings that change how the order sync behaves
These are set per connector in the Carriyo Dashboard, under the Shopify App connector.
| Setting | Effect |
|---|---|
| Create Shipment on Fulfillment | When on, a Shopify fulfillment creates a Carriyo shipment. When off, only the fulfillment is recorded |
| Enable Shipment Status Tracking | When off, Carriyo sends the tracking number but not the later delivery statuses |
| Use carrier tracking page | Sends the carrier's tracking page instead of the Carriyo tracking page |
| Shopify notification settings | Control whether Shopify emails your customer on fulfillment, tracking updates, and cancellation |
| Default delivery type and mapping | Map Shopify shipping codes to Carriyo delivery types, with a default when no mapping matches |
When a change takes a moment to appear
Updates travel between the two systems within seconds under normal conditions. A short delay is normal when either platform is busy or rate limiting requests.
If a change looks like it has not arrived:
- Check the order activity in the Carriyo Dashboard. Synced changes are recorded there against the order.
- Confirm the connector is active and the merchant is not paused.
Carriyo retries automatically when a request to Shopify does not go through the first time. If an order still looks out of step after a few minutes, contact support with the Shopify order number and we can trace it.