Once your Shopify store is connected and your products are imported, Qoblex keeps your orders in step with Shopify automatically. Every time an order is placed or changed in Shopify, Qoblex receives the update, matches it to your catalog and customers, and creates or updates the matching sale order in Qoblex. You do not import orders by hand for this to happen: the sync runs on its own in the background.
This article explains what triggers order sync, the direction it flows, how an incoming order is turned into a Qoblex sale order (customer matching, line items, allocations, taxes, invoices, payments, currency, and location), and exactly what happens when someone edits an existing order in Shopify. After reading it you will understand which fields carry across, why a Qoblex order looks the way it does, and where to look when an order does not appear as expected. Refunds, returns, and fulfillment are covered separately in How Shopify refunds, returns, and fulfillment sync work.
What triggers order sync and which way it flows
Order sync is one-directional: Shopify to Qoblex. Qoblex listens for changes in Shopify and mirrors them into your account. Editing an order inside Qoblex does not push that change back to Shopify through this sync.
There are two ways an order enters Qoblex:
- Automatic first fill after products import. As soon as your first product import from Shopify finishes, Qoblex automatically queues a one-time import of every order that is currently open in Shopify. You do not start this yourself: it is created for you at the end of the product import so your live orders are present from day one. This runs page by page through your open orders and hands each one to the same sync used for ongoing updates. (Bringing in older, already-closed historical orders is a separate manual action, described in Import historical Shopify orders.)
- Ongoing updates. After that, Qoblex reacts to changes in your Shopify store in real time, and each kind of change drives a specific behavior:
| What happens in Shopify | What Qoblex does |
|---|---|
| An order is created or edited (any change to the order) | Re-reads the whole order from Shopify and creates or updates the matching Qoblex sale order |
| An order is deleted | Treats it like an update: re-reads the order, and if Shopify reports it as cancelled the matching Qoblex sale order is cancelled |
| An order is fulfilled or partly fulfilled | Updates fulfillment (see article 06) |
| A refund is created | Updates the order for the refund (see article 06) |
What must be in place for an order to sync
An order will only turn into a Qoblex sale order when the surrounding setup is ready:
- The store is fully connected. The integration must be a live Shopify store with valid credentials. Temporary or half-connected stores are skipped.
- A product import has run. Orders are matched to products by the mappings created during product import, so line items only resolve once your catalog exists in Qoblex. See How Shopify product and inventory sync works.
- Your subscription is active. If your Qoblex plan has been expired for a week (7 days) or more, incoming Shopify orders are skipped rather than created.
- The order is not locked or legacy in Qoblex. If you have unlocked an order in Qoblex, or the order is an older-format (“v1”) order, Qoblex stops applying Shopify updates to it and records a notice on your activity feed instead. This protects manual changes you made in Qoblex from being overwritten.
How an order is matched and built
When Qoblex receives an order, it reads the complete order back from Shopify and then runs it through a fixed sequence of steps. Understanding this sequence explains what you see on the resulting Qoblex order.
Is this a new order or an edit?
Qoblex looks up whether it already holds a sale order for that Shopify order (matched on the Shopify order’s ID for your store and integration).
- No match: it creates a new sale order, then opens it (accepts it out of quote state) so it behaves like a normal live order.
- Match found: it updates the existing Qoblex order in place, re-reading its lines, totals, addresses, and status from Shopify. If Shopify now reports the order as cancelled, Qoblex cancels the matching order instead of updating it.
Customer matching
Qoblex attaches a customer to every order using the customer records in your account, reusing an existing contact where it can rather than creating duplicates:
- Company (wholesale) orders. If the Shopify order is placed on behalf of a purchasing company (B2B), Qoblex matches an existing customer by company name. If one exists it reuses it, refreshes its addresses, and adds the buyer as a contact person on that company. Otherwise it creates the company as a Wholesale customer. Orders tagged
wholesalein Shopify are also treated as Wholesale. - Retail orders. For a normal storefront order Qoblex matches an existing customer by email and name. If a match exists it reuses it (and restores it first if it had been deleted) and merges in any new addresses from the order. Otherwise it creates a new Retailer customer from the Shopify customer’s name, email, phone, and addresses.
- Guest / no customer. If the order carries no customer at all, Qoblex books it against a single built-in Anonymous customer contact so the order still has a home.
Line items and catalog matching
Each Shopify line item is matched to one of your Qoblex product variants so stock and cost are tracked correctly. Qoblex matches first on the Shopify variant mapping created during product import, and falls back to matching on SKU if the variant is not yet mapped. A Shopify “Tip” line that is not a real product is skipped. When an order is edited, existing Qoblex lines are recognised by their Shopify line ID so the edit updates the same lines rather than duplicating them.
Allocations (which location the stock comes from)
For lines that still need to ship, Qoblex reserves stock (an allocation) against the location Shopify assigned to that part of the order. It reads Shopify’s fulfillment orders that are still open, on hold, or in progress, maps each assigned Shopify location to its paired Qoblex location, and allocates the outstanding quantity there. If an assigned location is not mapped, Qoblex falls back to your default web-channel location, then to your first mapped location; if no location is mapped at all the allocation cannot be built and the sync fails with an error on your activity feed.
Order location
The order itself is stamped with a Qoblex location. If you have not set up any location mapping at all, Qoblex simply uses the integration’s default location. Once you have location mappings in place, Qoblex uses the location Shopify assigned to the order if it is mapped; if not, it uses the default web-channel location you set in your location mapping; and if neither applies it falls back to your first mapped location. Set this up under location mapping, described in Shopify locations, currency, and price lists.
Currency and exchange rate
If the order is in a different currency from your Qoblex base currency, Qoblex records an exchange rate on the order. On the first sync it derives the rate from the order (or looks it up), and it then keeps that same rate on later edits so a long-running order’s converted totals do not drift every time it is touched.
Order status
Qoblex sets the sale order’s status from the Shopify order’s financial and fulfillment status: a paid or fulfilled order becomes an open (or closed) sale order, while an order that is not yet actionable is held as a quote. A cancelled Shopify order cancels the Qoblex order.
Invoices and payments
Qoblex records payments and raises invoices from what Shopify reports, so your accounting follows the order automatically:
- It pulls the order’s payment transactions from Shopify and records each new one against the Qoblex order. On an edit, payments already recorded are not duplicated: only payments Qoblex has not seen before are added.
- It raises an invoice when the order has a new payment, or when the order is fully paid or refunded. A partially paid order with no new payment is left un-invoiced until the next payment arrives. Invoices raised this way are authorized automatically.
Order field mapping (Shopify to Qoblex)
The tables below list the order fields Qoblex reads from Shopify and where each one lands, derived from the live order sync request builders. Blank or missing Shopify values are handled as noted.
Order
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Order number | Order name | The Shopify order name (for example #1001) becomes the Qoblex order number. |
| Shopify reference | Order ID | The Shopify order’s ID is stored as the order’s external reference and is what Qoblex uses to match future updates to the same order. |
| Order date | createdAt | Stored in UTC. |
| Last updated | updatedAt | Stored in UTC. |
| Currency | Presentment currency (falls back to shop currency) | The currency the customer was charged in. |
| Exchange rate | Derived (see Currency and exchange rate above) | Set once on first sync and reused on later edits. |
| Tax inclusive | taxesIncluded | Marks whether line prices already include tax. |
| Source | sourceName | The Shopify sales channel/source that created the order. |
| Tags | Order tags | Shopify tags are joined into a comma-separated list. |
| Notes | Order note | The order note text. |
| Billing address | Billing address | Falls back to the customer’s address if the order has none. |
| Shipping address | Shipping address | Falls back to the customer’s address if the order has none. |
| Customer | Order customer / purchasing company | Resolved as described in Customer matching above. |
| Location | Assigned location / default web-channel location | Resolved as described in Order location above. |
| Status | Financial + fulfillment status | Mapped to open, closed, quote, or cancelled. |
| Refunds, fulfillments | Order refunds, fulfillments | Delegated to the refund and fulfillment sync (see article 06). |
Line item
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Line reference | Line item ID | Used to recognise the same line on an edit so it is updated, not duplicated. |
| Product variant | Variant ID, then SKU | Matched to a Qoblex variant by the Shopify variant mapping first, then by SKU. |
| Product name | Line item title / name | The item name shown on the line. |
| Quantity | Line item quantity | Defaults to 0 if Shopify sends none. |
| Price | Presentment unit price | The per-unit price in the order currency, taken from Shopify’s original presentment unit price. |
| Discount amount | Discount allocations (falls back to total discount) | When Shopify sends discount allocations they replace the line’s total-discount figure and are summed; otherwise the line’s total discount is used. |
| Tax amount | Tax lines | The sum of the line’s Shopify tax lines, in presentment currency. |
| Tax class | Tax line titles and rates | Built from the Shopify tax line titles and rates; a tax line priced at zero yields a zero-rate component, and a line with no tax at all becomes a zero-rate “Sales Tax Exempt” class. |
Allocation
| Qoblex field | Shopify field | Notes / transform |
|---|---|---|
| Item | Fulfillment-order line variant | Mapped to the Qoblex variant via the product mapping. |
| Location | Fulfillment order assigned location | Mapped to the paired Qoblex location. |
| Quantity | Fulfillable quantity | Only lines with a fulfillable quantity above zero are allocated, from fulfillment orders that are open, on hold, or in progress. |
What you see in Qoblex
A synced order appears as a normal sale order in Qoblex, under Sales > Orders, with:
- the Shopify order number (for example
#1001) as its order number and the Shopify order stored as its external reference, so it always maps back to the same order in Shopify; - the matched or newly created customer attached;
- line items matched to your products, with quantities, prices, discounts, and taxes;
- allocations against the correct location for anything still to ship;
- any invoices and payments Shopify has reported; and
- a confirmation on your activity feed reading
Order {number} synced successfully from Shopify.
If a sync cannot be completed, Qoblex records a notice on your activity feed describing the problem (for example a failure to create or update the order) so you can act on it.
