Restore real-time Shopify sync (webhooks)

Real-time sync is how your Shopify store tells MarginOS about a sale the moment it happens. When it stops, your numbers still update — just later, in batches, instead of within moments. To restore it, open Account Setup > Integrations, click Configure on the Shopify card, and press the button beside Real-time Data Sync Status: Setup Sync, Fix Sync or Retry Setup, depending on what the status line says. It runs while you wait and does not require reconnecting your store.

What real-time sync does

Once real-time sync is set up, Shopify sends MarginOS a short notice every time something that affects your money math changes:

• an order is placed, updated, or paid
• a customer record is created or changed
• a product or variant is created or changed
• MarginOS is uninstalled from your store

Refunds do not have a notice of their own. MarginOS reads them from the order they belong to whenever it fetches that order, and the background sweep described below picks up any it has not yet seen.

A notice is a nudge, not the data. MarginOS treats it as an instruction to go back to Shopify and fetch the full, current record for that order, customer or product. The figure that ends up in your margins is always Shopify’s own copy, never a summary lifted out of the notice — so a notice that arrives twice, late, or out of order cannot change what you see.

Three guarantees come with that:

• Only Shopify can talk to it. Every incoming notice carries a cryptographic signature from your store. MarginOS checks the signature before it accepts anything; unsigned or mis-signed traffic is rejected outright.
• A repeat delivery costs you nothing. Shopify re-sends a notice it thinks was not received. MarginOS records each delivery once, so a retried notice cannot double-count an order or a refund.
• Nothing is written back to your store. MarginOS reads orders, products and customers. The only thing it ever creates or removes on your store is its own notification subscriptions — which is exactly what the buttons below do.

Real-time sync changes how fast your numbers move, not whether they are right. MarginOS also runs a recurring background sweep that re-pulls Shopify data for any store it has not heard from recently, so a store with sync switched off still catches up — in batches, on the sweep’s schedule, rather than within moments of the sale.

Before you start

• Your store must already be connected. If the Shopify card reads Setup Required or Disconnected, start with Connect your Shopify store — there is no real-time sync to restore until the connection exists.
• You need the admin role on your MarginOS business. Account Setup is admin-only; anyone else sees Access Restricted — Advanced Configuration requires admin privileges.
• There is nothing to fetch from Shopify. No key, no token, no setting to change in the Shopify admin. MarginOS uses the connection you already authorised.

Restore real-time sync

1. Open Account Setup and choose the Integrations tab (/business-config/connections).
2. Find the Shopify card under Active Integrations and click Configure. The Shopify Configuration panel slides in from the right.
3. Scroll to Real-time Data Sync Status and read the line in the box. It tells you which of the five states below you are in.
4. Click the button on that line — Setup Sync, Fix Sync or Retry Setup. They all do the same job: MarginOS re-registers every notification it expects, skipping the ones already in place.
5. Watch for the message that appears in the corner. Real-time sync restored means every notification is registered. Partial sync restored means some registered and some did not. Webhook setup failed means none did.
6. Check the status line again. It should now read Real-time sync active with a count in brackets. If it does not, work through the row that matches your status in the table below.

What each status line means

Status line	What it means	What to do
Checking webhooks…	MarginOS is asking Shopify which notifications are currently live on your store.	Wait a moment. It resolves into one of the rows below.
Real-time sync active (8 webhooks)	Every notification MarginOS expects is registered on your store. Orders, customer changes and product edits reach MarginOS within moments.	Nothing. This is the healthy state. The number in brackets is how many notifications are live.
Partial sync (6/8 webhooks)	Some notifications registered and some did not. The second number is how many MarginOS expects. The events behind the missing ones will only reach you on the background sweep.	Click Fix Sync. If it stays partial, use Validate Permissions further down the same panel — a missing permission is the usual cause.
Real-time sync inactive	No notification is registered. Every change waits for the background sweep.	Click Setup Sync.
Webhook status unavailable	MarginOS asked Shopify for the list and got no usable answer. Most often the store connection is no longer valid.	Click Retry Setup. If MarginOS finds the connection has been revoked, it marks it as needing re-authentication and tells you to reconnect the store.

How MarginOS uses what arrives

Each notice sends MarginOS back to Shopify for the full record, and from there the data follows the same path as every other order in your account: the order is stored, its costs are attached from the best evidence available, it is assigned to an acquisition channel, and your margins, Command Center tiles and alerts are recomputed from the result. Nothing takes a shortcut because it arrived in real time — see How MarginOS turns raw data into your margins.

That is why restoring real-time sync does not, by itself, fill in a gap. Re-registering the notifications starts the flow again from that moment; the orders that happened while sync was off are picked up by the background sweep, which re-pulls recent Shopify data for stores that have gone quiet. Both routes end in the same place, with the same numbers.

The one thing real-time sync cannot fix is a cost MarginOS never received. An order that arrives within moments still shows an estimated fulfillment cost if no warehouse invoice has landed yet. Freshness and cost accuracy are separate axes: Data Trust levels grades the second one.

Example

A Friday-afternoon promotion brings in 42 orders between 4pm and 6pm. Your Shopify Configuration panel reads Partial sync (6/8 webhooks), and the two missing notifications are the ones that cover product changes.

Orders keep landing in MarginOS within moments, because the order notifications are among the six that are live. But the bundle you added to Shopify at lunchtime, and the two variants you re-priced for the promotion, do not reach MarginOS within moments — nothing told it they changed. They arrive only when the background sweep re-pulls your store.

Clicking Fix Sync on Friday evening registers the two missing notifications in a few seconds; the message reads Real-time sync restored and the status line flips to Real-time sync active (8 webhooks). From that point product changes reach MarginOS as you make them, and the lunchtime ones are picked up by the sweep rather than by you.

FAQ

How long does it take for real-time sync to come back?

A few seconds. Registration runs while you wait, and the status line re-checks itself as soon as it finishes. New events flow from that moment onward.

Is it safe to click Fix Sync more than once?

Yes. MarginOS looks at which notifications already exist on your store and leaves those alone, registering only the missing ones — so you cannot end up with duplicates or double-counted orders. It also clears out stale notifications left behind by an earlier MarginOS record for the same store.

Will I lose orders while real-time sync is off?

No. Real-time sync governs speed, not completeness. Orders, refunds and product changes that happen while it is off are collected by the recurring background sweep, which re-pulls Shopify data for stores it has not heard from recently. You see them later, not never.

Why does it say Partial sync instead of active?

Some of the notifications registered and some were rejected by Shopify. The most common reason is that your store connection is missing one of the permissions a particular event needs. Click Fix Sync first; if the count does not move, run Validate Permissions in the same panel to see which permission is absent.

What does Webhook status unavailable mean?

MarginOS asked Shopify which notifications are live and could not get an answer it trusts. Usually the access it was granted has been revoked or has expired. If Shopify explicitly rejects the credentials, MarginOS flags the connection as needing re-authentication and asks you to reconnect the store — the count on screen is left blank rather than guessed at.

Does MarginOS change anything in my Shopify store?

It never edits an order, a product, a customer or a store setting. The only writes MarginOS makes are to its own notification subscriptions — creating them when you click Setup Sync or Fix Sync, and removing stale ones that point at a MarginOS record you no longer use. Everything else is read-only.

What happens if I uninstall MarginOS from Shopify?

Your store tells MarginOS immediately. The connection is removed, the panel switches to Disconnected and Scheduled for Deletion with a live countdown, and an urgent alert titled Shopify App Uninstalled appears in your account. Your data is permanently purged within 48 hours unless you reinstall first, using Reinstall MarginOS on Shopify in the same panel.

Do I need to reconnect my store to fix real-time sync?

Usually not. Setup Sync and Fix Sync re-register the notifications using the connection you already have. Reconnecting is only the answer when the panel tells you the connection itself is invalid or needs re-authentication.

Related

• Connect your Shopify store
• How MarginOS turns raw data into your margins (the pipeline)
• How MarginOS assigns each order to a channel
• Data Trust levels: how MarginOS grades margin reliability
• Why MarginOS shows N/A instead of a made-up number
• Why a cost landed in Unmapped Costs
• Read the Command Center
• All data and integration guides