When a fulfillment or a refund happens in Shopify, Qoblex mirrors it automatically. You do not create the return, the refund, or the shipment by hand: Shopify notifies Qoblex, which finds the matching order, and it records the shipment, the return, the stock movement, and the accounting refund for you.
This article explains what each Shopify event triggers, the direction the data flows, how Qoblex decides whether returned stock comes back into inventory or not, and the exact field mapping Qoblex uses when it turns a Shopify refund into a Qoblex refund and a Shopify fulfillment into a Qoblex shipment. After reading it you will know what to expect in Qoblex after a Shopify refund or shipment, and where to look when one does not appear.
Direction of sync
This sync is one direction only: Shopify to Qoblex. Fulfillments, refunds, and returns that happen in Shopify flow into Qoblex. Qoblex does not push refunds or returns back to Shopify through this path. (Qoblex can push a shipment you create in Qoblex out to Shopify, which is covered in the order and fulfillment settings, but the refund and return sync described here is inbound only.)
What triggers the sync
Shopify notifies Qoblex when something happens to an order. Different real-world events trigger different reactions in Qoblex, and it matters which one:
| What happens in Shopify | What Qoblex does |
|---|---|
| You edit an order in Shopify | Runs the full order update (which is where shipments are built) and then the refund and return sync |
| Returned goods are disposed or restocked | Runs the refund and return sync |
| A fulfillment’s status changes (the order is fulfilled or partly fulfilled, a refund is created, or a fulfillment is moved, merged, put on hold, has a hold released, or is routed to a location) | Re-allocates the order’s fulfillable stock |
The events split into three groups, and it is important to know which one does what:
- Editing an order in Shopify does two things in sequence: it runs the order update, and it runs the refund and return sync. This is the only event that builds a Qoblex shipment from a Shopify fulfillment. The order-update run re-reads the order, rebuilds its shipments from Shopify’s fulfillments, and dispatches them (see Fulfillment field mapping below). Because a Shopify edit can also add or change a refund, the refund and return sync runs straight after.
- Disposing or restocking returned goods runs the refund and return sync only.
- Fulfilling an order, partly fulfilling it, creating a refund, or any fulfillment lifecycle change (moved, merged, put on hold, hold released, or routed) do not build a shipment and do not create a refund on their own. They enqueue a stock allocation for the order: Qoblex reads Shopify’s open fulfillment orders and reserves (allocates) the fulfillable quantity at the mapped location. No carrier, tracking number, dispatch, or refund is written by these events. The shipment itself is created later, when you next edit the order in Shopify.
Gating: when the sync runs (and when it waits)
- The store must be connected and the order must already exist in Qoblex. The refund and return pipeline loads the matching Qoblex order first, matching on the Shopify order id. If the order has not been imported yet, Qoblex logs that it cannot process the refund or return and stops. The refund will be picked up once the order exists.
- Refunds are processed for current-format orders only. The accounting refund step runs only for orders stored in the current internal format; older legacy orders skip the refund step. The return and stock steps still run.
- Orders that already carry a legacy restocked refund are skipped entirely. If the order in Qoblex already has a refund whose item was recorded with the legacy “return” restock type, the whole refund and return run is skipped for that order. This is a deliberate guard against reprocessing older restocked refunds, and it can explain a newer refund on the same order silently not appearing.
- Locations must be mapped. Every refund line and every fulfillment line resolves to a Qoblex location through your location mapping. If a location cannot be resolved, Qoblex stops and asks you to map that Shopify location in your integration settings.
- Events before your integration start date are treated carefully. For returns and no-restock adjustments dated before the day you connected the store, Qoblex either skips the stock adjustment or disables inventory tracking so that historical activity does not double-count against your current stock.
How Qoblex matches the record
- Order: matched by the Shopify order id against the order’s reference id in Qoblex.
- Existing refund: Qoblex looks for a refund already on the order with the same Shopify refund id. If it finds one that is already authorized, it leaves it alone. The accounting refund step is also skipped for orders that are not in the current internal format.
- Existing return: matched by the Shopify return reference. An already-authorized return is skipped so it is never processed twice.
- Shipment (fulfillment): Qoblex first tries to match on the Shopify fulfillment id. If there is no match, it falls back to matching an open shipment on the same order whose line items (product name and quantity) match the fulfillment.
Restock versus no-restock
When a refund or return happens, Qoblex decides per line whether the item comes back into stock. The decision is not a simple yes/no on Shopify’s restock flag: it also depends on whether the refunded line is linked to a shipment that Qoblex already dispatched.
- Restock (a return): the item comes back into inventory. This happens only when both conditions hold: (1) Shopify marks the line for restock (a return with disposition type RESTOCKED, or a pure refund whose restock type is return), and (2) the refunded line can be traced to a shipment Qoblex has already dispatched for that order. When both hold, Qoblex creates a return on the order, auto-assigns the batches or serials being returned, and authorizes the return so the stock is added back at the mapped location.
- No restock (refund only): the money is refunded but the goods do not re-enter stock (for example, a damaged item). This path runs only when Shopify’s restock type is no_restock and the refunded line is not linked to a dispatched shipment. Instead of a return, Qoblex records a stock adjustment that removes the refunded quantity, so your on-hand figure reflects that the goods are gone even though the customer was refunded. The adjustment is created and authorized automatically, with the reason “Shopify refund without restock” and a number in the form
sale#<order number>-R#<return reference>.
Because restock is gated on a dispatched shipment, refunding a line that was never shipped (for example a cancellation before fulfillment) does not add stock back and does not create a no-restock adjustment either; it is handled as a plain refund or an auto-cancellation return.
The refunded money itself is recorded separately by the accounting step for both cases, so a customer always sees their refund reflected in Qoblex regardless of the restock choice.
How the pipeline runs
For a refund or return event, Qoblex loads the order, builds the requests, and then runs them in order inside a single transaction:
- Load the order and its existing refunds, returns, and shipments.
- Build the requests from the Shopify refund and return data. If the order is cancelled and fully refunded in Shopify with no items already shipped, Qoblex builds an automatic cancellation that returns all unfulfilled items.
- Process returns (restock) so stock comes back at the mapped location.
- Process no-restock adjustments so refunded-but-not-restocked stock is removed.
- Record the refund in accounting.
If any step fails, the whole batch is rolled back, so you never end up with a half-applied refund.
Refund field mapping (Shopify to Qoblex)
Qoblex converts a Shopify refund into a Qoblex refund. A refund carries two kinds of lines: item lines (the products being refunded) and order-adjustment lines (amounts that are not products, such as extra refunds or shipping-related adjustments).
Refund header
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Reference id | Refund id |
Shopify refund id, stored so the refund is matched and not duplicated. |
| Status | (derived) | Set to Authorized, unless any of the refund’s Shopify transactions is still pending, in which case the refund is created as Draft. |
Refund item line (a refunded product)
Item lines are matched to an existing Qoblex order line by the Shopify line-item id. A refund line whose Shopify line item is not found on the order is skipped.
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Order item | (matched) | Matched to the Qoblex order line whose reference equals the Shopify refund line’s line_item_id. Unmatched lines are skipped. |
| Quantity | Refund line quantity |
Number of units refunded on this line. |
| Price | (from order line) | The existing Qoblex order-item price. It is the current price on the matched order line, not a value recomputed from the Shopify refund. |
| Reference id | Refund line id |
Shopify refund line id. |
Order-adjustment line (a non-product refund amount)
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Quantity | (fixed) | Always 1. |
| Price | Order adjustment amount (presentment amount) | Shopify sends the adjustment as a negative amount; Qoblex negates it so the refund line carries the expected sign. On tax-inclusive orders the adjustment tax is added into this amount first, so the price is tax-inclusive. |
| Tax class | (matched by rate) | Qoblex computes the adjustment’s tax rate from the presentment amount and tax amount, then matches it to one of your existing tax classes by comparing the rounded flat rate. If no tax class matches that rate, the refund sync fails for that order (see the callout below). |
| Product name | Order adjustment reason |
The Shopify adjustment reason is used as the line description. |
| Reference id | Order adjustment id |
Shopify order-adjustment id. |
Fulfillment field mapping (Shopify to Qoblex)
When a Shopify fulfillment reaches Qoblex as part of an order edit, Qoblex turns the fulfillment into a Qoblex shipment. The mapping from a Shopify fulfillment to a Qoblex shipment works as follows.
Shipment header
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Reference id | Fulfillment id |
Shopify fulfillment id, used to match the shipment later. |
| Tracking code | Fulfillment tracking number | The tracking number from the fulfillment’s first tracking entry, if any. |
| Shipment date | Fulfillment created_at |
Converted to UTC. |
| Status | Fulfillment status |
Dispatched by default; Cancelled when the Shopify fulfillment status is CANCELLED; Failed when it is FAILURE or ERROR. |
| Package delivered | (fixed) | Set to delivered. |
| Comments | (fixed) | Left blank on this path. |
| Location | Fulfillment location_id |
Mapped to a Qoblex location. If the location is not mapped, the sync stops and asks you to map that Shopify location. |
Shipment line item (per fulfilled line)
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Order item | (matched) | Matched to the Qoblex order line whose reference equals the Shopify fulfillment line’s line-item id. Lines that do not match an existing order item are skipped. |
| Quantity | Fulfillment line quantity |
Units shipped on this line. |
Once the shipment request is built, Qoblex creates or updates the shipment, allocates stock for the shipped items, and dispatches the shipment so your inventory reflects the goods leaving your warehouse. If a shipment cannot be dispatched (for example, insufficient stock to pick), Qoblex records a warning notification on the integration rather than failing silently.
What you will see in Qoblex
- After a Shopify fulfillment: the order’s fulfillable stock is allocated straight away. The shipment itself, with the tracking number, shipped quantities, location, and a dispatched status, appears when the matching order edit is processed.
- After a restock refund: a return appears on the order and the returned quantity comes back into stock at the mapped location. This happens only for lines that were shipped and marked for restock in Shopify.
- After a no-restock refund: an authorized stock adjustment removes the refunded quantity, with the reason “Shopify refund without restock” and a number like
sale#1042-R#987654321. - After any refund on a current-format order: the refund is recorded against the order in accounting, with the refunded quantities, any non-product adjustment lines, and a status of authorized (or draft while a Shopify transaction is still pending).