Troubleshoot your Shopify integration
Lesson 18 of 18 8 min read
Work out why an order, fulfilment, stock level or product didn't do what you expected, and how to fix it.
Most Shopify integration problems come down to a handful of causes: the Integration isn't running, a filter is excluding something, a SKU doesn't match, or a setting is on its default when you expected otherwise. In this lesson you'll learn a quick way to narrow down the cause, and how to fix the most common issues.
Start here
The first question tells you which side the problem is on. If the Document isn't in Supply Lens, look at the Shopify Integration and its Configuration. If it is, look at the Document itself and the Mapping onward.
Orders not arriving
Work through these in order:
- Is the Integration enabled? Check Activation on the tile.
- Is the store still linked? An
Uninstalledlabel means the connection has been lost. Reconnect it from the Supply Lens app in Shopify. - Does the order pass the filters? Compare the order in Shopify with
financialStatuses,fulfillmentStatuses,includePosandcustomerCountryFilter. An order onpendingpayment with the default list won't come in. - Was it created after
setupDate? - Is there an
importDelay? The order may simply not be due yet. - Are webhooks set up? Without them, you wait for the next scheduled run.
Orders held because of a SKU
When Supply Lens can't match a SKU, it holds the Document instead of creating a partial order.
- Open the held Document from Sales → Orders.
- Check the Logs section to find the unrecognised SKU.
- Check whether the SKU exists in your back-office system's item master.
- If it doesn't, add it, matching exactly what Shopify sends.
- If it does but the format differs (Shopify sends
WIDGET-001, the item master hasWidget001), either correct the source or add a cross-reference record in Supply Lens. - Reprocess the Document.
Tip
If the same SKU is missing from many orders, fix it in the item master first, then reprocess all the affected Documents in one go.
Other common symptoms
| Symptom | Likely cause | What to check |
|---|---|---|
| One Shopify order became two Documents | It spans two fulfilment locations | Normal behaviour; see the order splitting lesson |
| Gift card missing from the order | Lines without fulfilment orders are skipped | processLineItemsWithoutFulfillmentOrders |
| Reduced-rate line coded at standard rate | Shopify titles every UK rate GB VAT | Rate-qualified taxCodeIdentifiersByCountry |
| Tax code empty on a line | A rate combination has no code list entry | Add the missing code list entry |
| Wrong customer on orders | Default customer is forced, or identifiers don't match | alwaysSetDefaultCustomerId, identification rules |
| No shipping email | Off by default | notifyCustomer |
| Collect-in-store order marked fully ready too early | Partial shipment of a pickup order | splitPickupFulfillmentOrders |
| Metafield not written back | Value resolved to nothing, or no metafield definition | orderMetafieldMappings, Shopify metafield definitions |
| Negative stock in Shopify | Negatives sent as they are | preventNegativeQuantities |
| Product not stocked at a location | Location not active for that product | activateMissingLocations |
| Live products not updating | Only drafts are updated by default | updateActiveProducts, tagIncludeFilter |
| Product import brought nothing in | Dates or statuses | setupDate earlier than lastImportDate; productStatuses |
Getting help
If you've checked the Integration is enabled and the problem persists, contact the Support Team at support@supplylens.co.uk. Include the Integration ID from the tile, and the order or Document number, so they can find it quickly.
Hilltop Coffee's missing order
A customer emails Hilltop asking why their order hasn't shipped. Priya can't find it in
Supply Lens. The Integration is enabled and the store is linked. In Shopify, the order's
payment status is pending, because the customer paid by bank transfer. That isn't in
financialStatuses, so the order is correctly waiting. Once finance marks it paid in
Shopify, it comes through.
Recap
- First ask: is the Integration enabled, and does the Document exist in Supply Lens?
- Missing orders usually fail a filter, pre-date
setupDate, or are waiting onimportDelay. - Held orders usually mean a SKU mismatch: fix it, then reprocess.
- Many "wrong" results are settings on their defaults, such as
notifyCustomerorupdateActiveProducts. - Give Support the Integration ID and the Document number.
Quick guides for this topic
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.