Once your WooCommerce store is connected and your products are imported, Qoblex keeps your orders in step with WooCommerce automatically. Whenever an order is placed, edited, or cancelled in WooCommerce, Qoblex reads the full order back from your store, matches it to your catalog and customers, and creates or updates the matching sale order in Qoblex. You do not have to import these orders by hand: the sync runs on its own in the background. This article explains what triggers order sync, the direction it flows, and how an incoming WooCommerce order is turned into a Qoblex sale order (customer matching, line items, allocations, taxes, invoices, payments, currency, and location). It also explains exactly what happens when someone edits an existing order in WooCommerce. 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. Bringing in older orders that existed before you connected is a separate manual action, covered in Import historical WooCommerce orders.
What triggers order sync and which way it flows
Order sync is one-directional: WooCommerce to Qoblex. Qoblex listens for order changes in WooCommerce and mirrors them into your account. Pushing changes the other way (Qoblex to WooCommerce) is a separate feature described in How syncing orders from Qoblex to WooCommerce works. There are two ways a WooCommerce order reaches Qoblex: – Live webhooks. When you connect your store, Qoblex installs four order webhooks in WooCommerce: order created, order updated, order deleted, and order restored. Whenever any of these fire, WooCommerce calls Qoblex and Qoblex queues that order for processing in real time. – A safety-net poll every few minutes. Independently of webhooks, Qoblex checks your active WooCommerce stores on a short schedule and re-imports any order that was modified in the last several minutes. This catches orders whose webhook was missed or delayed, so a change is not lost if a single webhook fails to arrive. Whichever path an order arrives by, Qoblex handles it the same way: it re-reads the complete, current order from WooCommerce and re-applies it, rather than trying to patch individual fields.
In WooCommerce, an order being created and an order being edited both arrive as an order webhook, and Qoblex processes them identically. Because Qoblex always re-reads the whole order, an edit in WooCommerce (adding a line, changing a quantity, editing an address, applying a fee or shipping change) reliably flows through to the matching Qoblex order.
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 connected with valid credentials. The order sync reads the order back from WooCommerce using your stored store connection, so the integration must be a live, authorized WooCommerce store. – Your products are imported. Order lines are matched to your catalog by the product mappings created during product import (and by SKU), so lines only resolve to a Qoblex product once your catalog exists in Qoblex. See How WooCommerce product and inventory sync works. – A location is set for the integration. The order must be able to resolve to a Qoblex location; if the integration has no usable location the order cannot be built. Allocations additionally require at least one order location to be configured. See WooCommerce locations, currency, and price lists. – Your subscription is active. The safety-net poll skips any store whose Qoblex plan has expired, so orders are not imported for an expired account.
How an order is matched and built
When Qoblex processes an order, it reads the complete order back from WooCommerce and then runs it through a fixed sequence of steps inside a single database transaction. If any step fails, the whole order is rolled back and a notice is written to your activity feed, so you never get a half-built order. 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 WooCommerce order, matched on the WooCommerce order ID for your store and integration. – No match: it creates a new sale order. If the new order is not a quote-only status, it is opened (accepted 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, extra charges, totals, addresses, and status from WooCommerce. – Cancelled in WooCommerce: if the WooCommerce order status is cancelled or trash, Qoblex cancels the matching Qoblex order instead of updating it. As part of the cancellation Qoblex first returns any shipped items and refunds any pending invoiced items so stock and accounting are unwound cleanly.
Customer matching
Qoblex attaches a customer to every order, reusing an existing contact where it can rather than creating duplicates: – Orders with a WooCommerce customer account. Qoblex reads the customer from WooCommerce and builds a contact from their name, email, phone, and billing/shipping addresses. If the customer’s billing or shipping carries a company name, that company name becomes the contact’s name and the person’s name is kept as the contact person. – Matching to an existing contact. Qoblex looks for an existing customer with the same email and the same contact-person name. If it finds one, it reuses that contact and updates its details; if not, it creates a new customer. – Guest orders (no customer account). If the order has no WooCommerce customer, Qoblex builds an anonymous customer from the order’s billing and shipping name, company, and addresses so the order still has a home.
When a guest order has no billing email, Qoblex uses the placeholder address anonymous_customer@noemail.com so the contact can still be saved. If you later see a customer with that unusual email, that is why; you can edit the contact in Qoblex.
Line items and catalog matching
Each WooCommerce line item is matched to one of your Qoblex product variants so stock and cost are tracked correctly. Qoblex matches first on the WooCommerce product/variation mapping created during product import, and falls back to matching on SKU when no mapping is found. When an order is edited, Qoblex recognises existing Qoblex lines by their WooCommerce line ID so the edit updates the same line rather than duplicating it. If a plugin changes a line’s ID on an existing order, Qoblex also tries to re-link the line by matching its name and quantity, to avoid breaking a line that has already been shipped or invoiced. Shipping charges and fee lines from WooCommerce are brought in as extra-charge lines on the Qoblex order, each named after its WooCommerce shipping method or fee.
Taxes
Qoblex builds a tax class for each line from the WooCommerce tax lines that actually apply to it. A tax line priced at zero percent is ignored, and a line with no applicable tax at all becomes a zero-rate Sales Tax Exempt class. If a matching tax class already exists in your account (same number of components and the same overall rate), Qoblex reuses it rather than creating a duplicate.
WooCommerce line prices are always read as tax-exclusive. Qoblex records each line’s price without tax and adds the tax amount separately, regardless of how prices are displayed at your WooCommerce checkout.
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 looks up the rate between your base currency and the order currency, and it then keeps that same rate on later edits so a long-running order’s converted totals do not drift every time the order is touched.
Order location
The order itself is stamped with a Qoblex location. Qoblex uses the first order location you configured for the store; if you have no order locations set, it uses your first inventory location; and if neither is set it falls back to the integration’s first location mapping. If none of these can be resolved, the order cannot be built and the sync fails with a notice on your activity feed. Set these up under location mapping, described in WooCommerce locations, currency, and price lists.
Order status
Qoblex sets the sale order’s status from the WooCommerce order status: – completed, shipped, or delivered becomes a closed sale order; – cancelled or trash cancels the Qoblex order (a trashed WooCommerce order is treated the same as a cancelled one, not left as a live quote); – refunded or checkout-draft is held as a quote; – any other status becomes an open sale order (unless the Algeria shipping integration is enabled for your account, in which case the order is held as a quote until it is actioned).
Allocations (which location the stock comes from)
For an open or closed order, Qoblex reserves stock (an allocation) so the order can be shipped. It works down your configured order locations in order, allocating each line’s outstanding quantity from the first location that has stock available, then moving to the next location for anything still unallocated. When you re-sync an order that is already allocated, Qoblex accounts for the stock this order already holds so it is not double-counted. Allocations against locations you have since removed from your order-location list are preserved rather than silently released. Allocations are skipped for orders that are cancelled or still in quote state, for stores with no default location, and when no order locations are configured.
Invoices and payments
Qoblex raises invoices and records payments from what WooCommerce reports, so your accounting follows the order automatically: – An invoice is raised only when the order is closed and there is still an uninvoiced quantity to invoice. The invoice is authorized automatically. An order that is not yet closed, or one that is already fully invoiced, is left as-is. – When an invoice is raised, Qoblex records the WooCommerce order total as a payment against the order, dated on the WooCommerce payment date. If the order total is zero, no payment is recorded.
Order field mapping (WooCommerce to Qoblex)
The tables below list the order fields Qoblex reads from WooCommerce and where each one lands, derived from the order sync request builders. Blank or missing WooCommerce values are handled as noted.
Order
| Qoblex field | WooCommerce field | Notes / transform |
|---|---|---|
| Order number | Order number | The WooCommerce order number becomes the Qoblex order number. |
| WooCommerce reference | Order ID | The WooCommerce order ID is stored as the order’s external reference and is what Qoblex uses to match future updates to the same order. |
| Order date | date_created_gmt |
Stored in UTC. |
| Last updated | date_modified_gmt |
Stored in UTC. |
| Currency | Order currency | The currency the order was placed in. |
| Exchange rate | Derived (see Currency and exchange rate above) | Set once on first sync and reused on later edits. |
| Tax inclusive | Always No | WooCommerce line prices are read as tax-exclusive. |
| Notes | Customer note | The customer note text from the order. |
| Billing address | Billing address | Falls back to the matched customer’s first address if the order has none. |
| Shipping address | Shipping address | Falls back to the matched customer’s first address if the order has none. |
| Customer | Order customer (or guest) | Resolved as described in Customer matching above. |
| Location | First order location (then first inventory location, then first mapping) | Resolved as described in Order location above. |
| Status | Order status | Mapped to open, closed, quote, or cancelled as described in Order status above. Both cancelled and trash cancel the matching Qoblex order. |
| ### Line item | ||
| Line reference | Line item ID | Used to recognise the same line on an edit so it is updated, not duplicated. |
| Product variant | Variation ID / Product ID, then SKU | Matched to a Qoblex variant by the WooCommerce product mapping first, then by SKU. A variation’s ID is used when present, otherwise the parent product ID. |
| Product name | Line item name | The item name shown on the line. |
| Quantity | Line item quantity | The ordered quantity. |
| Price (per unit) | subtotal divided by quantity |
The pre-discount per-unit price, derived from the WooCommerce line subtotal and quantity. |
| Discount amount | subtotal minus total |
The line discount, calculated as the difference between the line subtotal and the line total. |
| Tax amount | total_tax |
The line’s total tax, in the order currency. |
| Tax class | Order tax lines applied to the line | Built from the WooCommerce tax lines that apply to the line; a line with no applicable tax becomes a zero-rate Sales Tax Exempt class. |
| ### Extra charges (shipping and fees) | ||
| Charge reference | Shipping line ID / fee line ID | Used to recognise the same charge on an edit. |
| Name | Shipping method title / fee name | Shown on the extra-charge line. |
| Amount | Shipping total / fee total |
The charge amount, quantity 1. |
| Tax amount | Shipping total_tax / fee total_tax |
The tax on the charge. |
| ### Allocation | ||
| Qoblex field | WooCommerce source | Notes / transform |
| Item | The order’s matched product variant | Only variants found in your catalog are allocated. |
| Location | Your configured order locations, in order | Stock is taken from the first order location with availability, then the next for any remainder. |
| Quantity | Outstanding quantity to ship | Zero allocations are ignored; the order’s own existing reservation is accounted for on re-sync. |
| ## What you see in Qoblex | ||
| A synced order appears as a normal sale order in Qoblex, under Sales, with: | ||
| – the WooCommerce order number as its order number and the WooCommerce order stored as its external reference, so it always maps back to the same order in WooCommerce; | ||
| – the matched or newly created customer attached; | ||
| – line items matched to your products, with quantities, prices, discounts, and taxes, plus any shipping and fee lines as extra charges; | ||
| – allocations against your order locations for anything still to ship; | ||
| – any invoice and payment raised once the order is closed; and | ||
| – a confirmation on your activity feed reading that the order was successfully processed from WooCommerce. | ||
| If a sync cannot be completed, Qoblex rolls the order back and records a notice on your activity feed describing the problem (for example a missing location, or a customer that could not be created) so you can act on it. | ||
| ## Troubleshooting order sync |
anonymous_customer@noemail.com so the contact can be saved, and builds the customer from the order’s billing and shipping details. Edit the contact in Qoblex if you need to correct it.