Resolve preparation and inventory-sync problems
Use this guide when Home shows a health warning, preparation won't finish, or a stock change in Zapstra doesn't reach Shopify. Find what you see, then follow the steps.
A dot in System health isn't green
System health on Home has one dot per check. Green is fine, amber needs a look, red needs attention and grey means Zapstra is still checking (not zero, and not a failure).
| Dot | Amber or red usually means | What to do |
|---|---|---|
| Shopify updates | Zapstra is still connecting to Shopify's change notifications, or the connection needs attention. | Select it to open preparation details. Wait while it connects; if it needs attention, use the recovery action shown. |
| Workspace prepared | Preparation is still running, finished with warnings, or needs another try. | Select it, then see Preparation is stuck or needs attention below. |
| Live sync | Live sync is paused, or catching up after a pause. | See Live sync is paused below. |
| Shops count | No linked shops: no store is connected. | Reconnect the store. See Connect stores. |
Preparation is stuck or needs attention
- Choose View preparation details on Home (or select Workspace prepared in System health).
- Open the current run and see which step is waiting or needs attention.
- If a run is still going, let it finish. Don't start another.
- If the card offers Retry, use it for the failed step.
- Use Run full refresh only when you need a fresh run, then follow View refresh progress.
Check the result: the preparation card goes away and the dots turn green. If a row keeps saying Needs attention, contact Support with the reference shown.
Live sync is paused
Home shows Live sync is paused, with the last time it synced. This happens after the workspace was paused, or when billing needs attention.
- An admin chooses Resume live sync. If a plan is needed first, the banner shows Choose a live-operations plan instead.
- If you see Check billing status, open Billing and check the subscription.
- While Home shows Catching up on changes made while paused, wait for it to finish. If catch-up is still pending, use Retry catch-up.
Your workspace and history stay available while paused. See Billing management and Pause operations or uninstall.
Stock changed in Zapstra but not in Shopify
Check these in order:
- The shop is managed. On Inventory → Locations & pools → Inventory management, the shop shows Managed in Zapstra. If it shows Not managed yet, Zapstra doesn't write to it. See Start managing inventory in Zapstra.
- Updates are on. The shop shows Updates to Shopify: On. If Paused, choose Resume updates to Shopify. If Restore inventory updates appears, follow it.
- The location is managed. On Locations, the location is Managed, not Not managed.
- The product is managed. It isn't waiting under products that need attention, such as Fix negative stock or a change in Changes made in Shopify.
- The stock row is syncing. In the material's Stock Levels, the row's menu shows Already syncing to your store. If it offers Start syncing to your store, start it.
- Live sync is on. System health shows a green Live sync dot.
Find the step that's off before changing quantities again. Changing a number twice can double-count it.
A banner or message on another page
| What you see | What it means | What to do |
|---|---|---|
| Review inventory management | Some shops are Not managed yet, so this work won't update their Shopify stock. | Choose Review inventory setup. |
| Updates to Shopify are paused | Updates are paused for the shops listed. | Review Inventory management before receiving or adjusting. |
| Your Shopify stock is not being updated (on the Get set up checklist) | Stock was recorded while the shop wasn't managed in Zapstra. | Start Set up inventory management. |
| "{location} isn't managed in Zapstra" | That location is set to Not managed. | Change it on Locations if Zapstra should act there. |
| Stock recorded with a syncing message | The stock change saved; only syncing didn't start. | Fix the stated cause, then Start syncing. Don't record the change again. |
| Refresh your store's numbers first | The store's numbers are out of date. | Refresh the store data, then return to the same row. |
| Fix the stock mismatch first | Zapstra and Shopify disagree. | Resolve it in Reconciliation and activity. |
| Open Zapstra Inventory Management from your Shopify admin | The app was opened outside Shopify admin, or the session expired. | Choose Open Shopify admin and open the app from Apps. |
| Zapstra Inventory Management needs permission to change inventory in this store | The app needs an updated Shopify permission. | Open the app from Shopify admin and approve the permissions. |
Get diagnostics for support
- On Home, choose View details in System health.
- On System Health, choose Refresh and note the Last checked time.
- If support asks, choose Export JSON and attach the file.
Include the record numbers (purchase order, receipt, material) in your support ticket too; System Health checks the connection, not individual records.