Shopify Sync and Webhooks

After you've imported products from Shopify, Peasy can keep Shopify orders and linked inventory items connected. Peasy remains the place where your real inventory is managed; Shopify sends orders into Peasy and can receive updated counts from Peasy depending on your sync settings.

How to Get There

Click Configure (gear icon) in the sidebar, select Integrations, then open Shopify. Use Inventory Sync Direction on the General tab to choose how counts should flow. Use Webhooks to review incoming delivery and recovery activity, and use History to review inventory sync and fulfillment activity.

How Sync Works

Peasy Is the Source of Truth

Peasy is the source of truth for actual inventory. Receives, production, sales, counts, transfers, and manual adjustments in Peasy determine what you have available.

When Peasy sends inventory to Shopify, it calculates the Shopify quantity from the linked Peasy item family and unit conversion. Peasy sends that number as Shopify's On hand count, the shelf count. Shopify then subtracts the units its own open orders hold and shows the rest as Available. So a lower Available than On hand while orders are open is expected, not a sync problem. This helps your online store avoid overselling.

Peasy allows an on-hand count below zero so your inventory still reflects what actually happened. Shopify cannot accept a negative On hand count, so Peasy sends zero to Shopify while keeping the real negative count in Peasy. Shopify can still show a negative Available count when open orders hold more units than its zero on-hand count. That negative Available is expected and does not change Peasy's actual count.

In Sync History, each displayed inventory quantity says which Shopify state it represents. Push and pull rows say on hand. Automatic webhook rows and starting inventory imported from Shopify say available. A skipped row shows no quantity or state because Peasy did not send a count. When Shopify changes an item's count several times before Peasy catches up, Sync History can show one combined change (for example 10 → 5) instead of each step in between; the final count is the same.

When Peasy Sends Counts

With Peasy-to-Shopify sync turned on, every change to an item's stock in Peasy sends the new count to Shopify: receiving a purchase order, a work order, a transfer, a sale or a cancelled shipment, a count, an adjustment, a Beacon action, or an import from a spreadsheet or another channel. Starting counts that come from Shopify itself — a Shopify product import or Pull all from Shopify — are not sent back, because they are already Shopify's numbers. The update usually reaches Shopify within a few seconds, and always within about a minute. If Shopify is busy or down, Peasy tries again automatically instead of dropping the update.

On stores Peasy has moved to the updated behavior, a change that Shopify itself caused — a fulfillment, a cancelled shipment, or a return — also sends Peasy's count back, so Shopify stays in step with Peasy. Peasy does this only for an item you have already changed in Peasy (with a count, an adjustment, a receipt, or any other Peasy change) or pulled with Pull all from Shopify. For an item nobody has changed in Peasy yet, Peasy leaves Shopify's own count alone, and Sync History shows the update as Skipped with the message "Peasy has not sent a count for this item yet, so Shopify keeps its own." Any change you make to that item in Peasy starts sending its count, and it keeps sending from then on. On other stores, Shopify's own sales never send a count back and nothing appears in Sync History for them; Shopify already changed its own count.

If several Shopify variants map to the same Peasy variant, Peasy sends the same converted on-hand quantity to every mapped Shopify variant. It does not divide the quantity between those listings. A failure on one listing is recorded separately and does not prevent Peasy from updating the others.

In Shopify Admin, a count sent by Peasy appears in the item's inventory history as an Inventory correction attributed to Peasy. Open that correction to see the Peasy inventory item reference behind the update.

Shopify Orders

This is how Shopify orders work on most stores. If Peasy has moved your store to the updated behavior, read Shopify Orders on Updated Stores instead.

When Shopify-to-Peasy sync is enabled, Shopify orders flow into Peasy as sales activity. Peasy adds the order to the current consolidated Shopify sales order and deducts inventory when Shopify fulfills the order, recording the deduction as a shipment so it's consistent with the rest of Peasy.

To control which Peasy location is deducted, open Shopify's General tab and scroll to Location Mapping. Map each active Shopify location to the active Peasy location that holds that inventory. When Shopify reports the location that fulfilled an order, Peasy uses that mapping on both the shipment and its lines. A consolidated order can therefore contain separate fulfillments from different locations, even when they ship on the same date.

If the Shopify location is not mapped, the saved mapping is inactive, or the mapped Peasy location is inactive, Peasy keeps the existing fallback: the shipment uses the order's Ship from location, which comes from the customer's default and then the business default when no customer default is set.

Each Shopify order or refund line keeps its own Shopify identity even when multiple variants map to one Peasy variant. Their quantities apply independently to the shared Peasy inventory pool; Peasy does not merge or discard the lines just because their destination item is the same.

The daily or weekly consolidated order setting only controls how Shopify orders are grouped in Peasy. It does not wait until the end of the day or week to deduct inventory.

Shopify Orders on Updated Stores

Peasy is moving Shopify stores one at a time to an updated way of handling orders. Everything in this section applies only after your store moves, and only to orders placed from then on.

If you connect Shopify to Peasy for the first time, your store starts on the updated behavior right away, so there is no later switch. Disconnecting and reconnecting a store does not change which behavior it uses.

When an order is placed. Peasy reserves the stock for it. Your available quantity drops and your on-hand quantity stays the same, because nothing has left the shelf yet. See Understanding Availability.

When Shopify fulfills the order. The stock comes off the shelf from your oldest lots first, and the reservation shrinks by the same amount. A partial fulfillment deducts only what shipped and leaves the rest reserved.

Which location it comes off. When Shopify assigns part of an order to a fulfillment location, Peasy moves that part of the open reservation to the mapped Peasy location. That accepted location stays with the reservation even if you change the mapping later. Units Shopify has not assigned stay reserved at the original location. A fulfillment releases each share from its reserved location. It deducts an assigned share from its accepted location. For an unassigned share, it deducts from the fulfillment location's current Peasy mapping when one is available; otherwise, it uses the reservation location. On a store with more than one active Shopify location, Peasy does not guess when an assigned location is unmapped or maps to an inactive Peasy location; that share waits until the mapping is fixed.

Where to find the order. Go to Inventory > Logs. Each fulfillment movement is a Sale row with Shopify as its source, its Customer reads Shopify, and its Transaction ID is the Shopify order ID. While part of the order is still waiting to ship, that quantity shows as a pending Unfulfilled row with the same Source, Customer, and Transaction ID. To see only these rows, choose Shopify in the Customer filter or search for "Shopify". Click that Transaction ID to open the order under Configure > Integrations > Shopify > History. Posted fulfillments also appear in the All and Orders History filters. Each order also has an Order Created row there showing the order total (for example USD 25.00), and a cancelled order also has an Order Cancelled row showing Shopify's cancel reason. This includes orders on a store with Shopify-to-Peasy sync turned off: Peasy lists them but does not reserve or deduct stock for them, and clicking one opens the order with a note that it was not synced into Peasy. If Peasy could not reserve stock for some or all of an order's lines — for example because a Shopify product is not linked to a Peasy item — its Order Created row shows Blocked. To find every blocked order, set the History status filter to Blocked. Click any order row to open the order's details. Each blocked line there says what the problem is and why, and Peasy reserves and deducts nothing for it until the cause is fixed. Click Ask Beacon how to fix this on the line for step-by-step help. After you fix the cause, the line stops showing as blocked right away, and Peasy finishes the order on its own the next time it rechecks blocked orders. You don't need to retry anything. In the All view, the row shows the order reference under Description, Fulfillment under Type, Order Fulfilled (-quantity) under Details, Success under Status, the fulfillment time, and Shopify under User. The negative number is the quantity fulfilled, not Shopify's on-hand count. Reservations are not shown in History. The order does not appear under Sell > Sales Orders, and Peasy no longer creates a customer or a shipment for it. Nothing is lost: the order lives in Inventory Logs and your Shopify order history, and Sell > Customers lists it under Shopify. When the store has Shopify orders in the last 30 days, a Shopify bar on the Customers page opens a Shopify sales page with each order's date, units, revenue and cost. See Managing Customers.

In your sales reports. The Month-end COGS report and Beacon's sales answers count each Shopify order the way they count a Peasy sales order: on the date it was placed, whether or not it has shipped. In the report it is a Shopify order row. Units that shipped carry the cost of the lot they came from. Units not shipped yet carry an estimate from the recipe or buy price, the same estimate a Peasy sales order gets, and a row Peasy cannot price is marked incomplete rather than shown at $0. A refund that puts stock back lowers the sale; a money-only refund does not. Beacon also lists these orders among your recent sales, with Shopify as the customer, and opens one when you ask for it by its Shopify order name, such as #1234. Its business overview counts the Shopify orders sold in the last 30 days.

When the order changes:

• An edit or a cancellation before anything ships releases the reserved stock that hasn't shipped, and your available quantity goes back up.
• A shipment cancelled after it went out — Shopify marks the fulfillment cancelled or failed — puts that shipment's stock back once, on the same lots and location it came from. It appears as a Shipment Cancelled row dated when Peasy received the change, and the order's reserved stock goes back up for the units still to ship.
• A refund with a return puts the returned units back on the exact lot and location they shipped from, once. It appears as a Return row.
• A refund with no return, or a money-only refund, moves no stock. The goods never came back, so nothing goes back on the shelf.

What doesn't change:

• Every Shopify order from before the switch stays exactly where it is, with its sales order, customer, and shipment. Nothing is moved, archived, or unlinked, and you don't need to clean any of it up.
• Peasy still sends your on-hand count to Shopify when you change stock in Peasy, and can still pull counts back. After the switch, a Shopify fulfillment, cancellation, or return also sends Peasy's count back for items you have changed in Peasy — see When Peasy Sends Counts.
• Your item links, location mapping, and Inventory Sync Direction setting all keep working the same way.

One limit. If a customer returns goods from a shipment that went out before your store moved, Peasy does not put that stock back for you. Handle it the way you do today — record the return or adjust the count yourself. Peasy can only return stock to a lot it deducted under the updated behavior.

Peasy also records the attempt. That refund's Shopify notification stops after retrying and appears under Needs attention on the Webhooks tab, with Action needed on the health card. That is expected, and it is safe to leave there — retrying it will not put back stock from a shipment that went out before the switch.

Shopify Inventory Counts

Shopify inventory-count updates are handled differently from Shopify orders. Automatic Shopify inventory-count notifications update Peasy's Shopify-side comparison data and sync history, even when Shopify-to-Peasy inventory sync is turned off. They do not overwrite Peasy's actual inventory count.

Shopify counts can set Peasy inventory only in explicit actions:

1. Initial Shopify import — if Shopify-to-Peasy inventory sync is enabled, Peasy can use Shopify quantities as starting inventory.
2. Bulk pull — on the Shopify settings page, Pull all from Shopify is a one-time action for every linked item. It adopts Shopify's On hand count, which includes units held for open orders, and it shows a preview comparing current Shopify and Peasy quantities before you confirm. The same page also offers Push all to Shopify when Peasy has the correct counts. Neither action changes your automatic Inventory Sync Direction setting above. These buttons are disabled until at least one active Shopify location is mapped to a Peasy location.

Choosing a Shopify source when you pull

When several Shopify variants are linked to the same Peasy inventory pool, only one of their counts can reset that pool. Peasy settles this on its own when there is no real choice to make — only one variant is stocked, or every variant works out to the same result — and lists what it handled under Automatically handled at the top of the preview.

Everything else appears under sources need review, one card per Shopify variant showing its title, Shopify SKU, and the count at each mapped location. Pick the card whose count should reset the pool. The info icon on a card shows the Peasy item that variant is linked to, including its SKU, unit, and price, so you can confirm the link before choosing.

When one variant has stock and the others read zero, Peasy pre-selects the one with stock, since a zero usually means that variant isn't the one you count. That is a guess, so the pool still appears in the review list with the guess already filled in — apply as-is to accept it, or pick a zero card if the zero is the real count.

Pools where Shopify does not stock any linked variant are left alone — the preview marks them Skipped and shows the Peasy count staying where it is.

Inventory Sync Direction

New Shopify connections start with inventory sync paused so you can import products, review units, and choose the direction that fits your workflow.

If an older Peasy-to-Shopify-only connection is missing comparison counts for a product, contact support to run a full Shopify catalog sync. That fetches the current Shopify stocking locations before you rely on comparison or push history; changing the sync direction does not fill an older gap by itself.

What Stays in Sync

New Product Alerts

When you add new products in Shopify after the initial import, Peasy doesn't import them automatically. Instead, you'll see an alert letting you know there are new Shopify products available to import. You can then go to the Shopify settings page to review and import them.

Reviewing New Products

When you add new products in Shopify and import them into Peasy, they go through a staging process before becoming live items:

1. Data lands in staging — Imported products appear in a review area, not directly in your inventory.
2. You review and organize — Check names, categories, units, and groupings. Peasy's AI may suggest groupings and matches.
3. You confirm the import — Only after you approve does Peasy create the actual items.

In staging, you can:

• Edit item names and fix typos before items are created
• Group variants — Multiple Shopify variants can be grouped under one parent item
• Set units and conversions — Define buy/sell units and conversion ratios
• Match to existing items — Link incoming items to items already in Peasy instead of creating duplicates
• Import partially — Import some items now and leave others in staging for later

See Importing from Shopify for the full import flow.

Reviewing Webhook Recovery

Open the Webhooks tab to check whether Shopify deliveries are moving through Peasy. The health card summarizes work that is due, deliveries being processed, expired processing attempts, deliveries that have stopped, and the last automatic recovery progress. The page shows a snapshot from when it was loaded or last refreshed, so refresh it when you check back for updated recovery status.

The badge on the card tells you what to do next:

• Healthy — nothing is waiting for recovery. No action needed.
• Recovering — Peasy is catching up on delayed deliveries. Check back shortly.
• Waiting — deliveries came in a moment ago and recovery hasn't picked them up yet. Check back shortly and refresh the page. If recovery is overdue, the refreshed card will show Stalled.
• Stalled — recovery is overdue or has stopped moving deliveries through. Contact support.
• Action needed — at least one delivery has stopped and should be reviewed. It does not mean every Shopify delivery has stopped.
• Paused — automatic recovery is currently turned off for this environment.

Use the two views below the health card:

• Recent shows the newest deliveries.
• Needs attention searches all deliveries for the Shopify connection and shows the parked, exhausted, or terminal deliveries that need review. The results are not limited to the newest page.

Use Previous and Next to move through additional results. Select a row or choose View details to see its status, attempts, timing, and error category. The stored webhook payload is not shown.

In Result, no op means the updated order handling found that the delivery was already applied or older than the current order. legacy no op means the earlier order handling finished without making a change. ignored means Peasy received the delivery but had nothing to apply. All three are successful results and stay out of Needs attention.

On a busy day Shopify often sends several updates for the same order, product, or inventory level before Peasy has processed the first one. Only the newest one matters, so Peasy marks each older waiting update Skipped with Result ignored and the message "Superseded by a newer Shopify snapshot of the same object", and processes the newest one in the older one's place in line. A superseded update is a successful result, not a problem, and stays out of Needs attention.

Deliveries whose Topic starts with fulfillment_orders/ arrive once your store has granted Peasy's fulfillment permission. Shopify sends them when it decides, or changes, which of your locations ships each part of an order. On updated stores, Peasy uses those assignments to move the affected open reservation between mapped locations. On-hand quantity does not change until Shopify reports a fulfillment.

You can retry a stopped delivery after reviewing it. Retry is unavailable while a delivery is still processing; Peasy's automatic recovery handles processing attempts whose lease has expired.

Good to Know

• Which way is my store set up? — Place a low-quantity test order in Shopify and let it fulfill. If it shows up under Sell > Sales Orders, your store is still on the behavior described in Shopify Orders. If it appears only in Inventory > Logs as a Shopify Sale row, your store has moved to the updated behavior. Contact support if you want it confirmed.
• Shopify orders deduct quickly — order activity normally appears in Peasy within seconds to minutes when Shopify-to-Peasy sync is enabled.
• A brief Peasy outage delays orders, it doesn't lose them — if Peasy can't record an incoming Shopify order, it tells Shopify the order wasn't received rather than accepting it. Shopify then sends it again, so the order arrives late instead of being missed. You don't need to do anything; if orders from a specific window never appear at all, contact support.
• Peasy counts do not get overwritten by normal Shopify count notifications — Shopify-side count changes update comparison and history data unless you explicitly import or use Pull all from Shopify.
• Loop prevention — Peasy has built-in safeguards to prevent sync loops where a Peasy change bounces back from Shopify.
• Sync logs — Peasy tracks sync events, so you can see what was pushed or pulled and when.
• Needs attention covers the full delivery history — use this Webhooks view when the health card reports Action needed, then page through the results until you find the stopped delivery.
• With Shopify-to-Peasy sync turned off, deliveries show as Skipped — Peasy still records the order for your history, but deliberately does not apply it to your counts, so the delivery finishes as Skipped rather than needing review. If your store has sync turned off and the health card shows a large Due now number that never goes down, those are older deliveries from before this behavior was corrected; they are not blocking anything and no new order is affected. Contact support if you want that history brought into Peasy.
• Only linked items sync — Items that were imported from Shopify (or manually linked) participate in sync. Unlinked items are independent.
• Shared mappings remain independent — Multiple Shopify variants can map to one Peasy sell variant, while each link keeps its own sync history and can be unlinked separately.
• Multiple Shopify locations can share one Peasy location — If you map one Peasy location to multiple Shopify locations, Peasy sends that Peasy location's live quantity to each mapped Shopify location where the item is stocked. Shopify may count those location quantities separately for online selling, so this can make the sellable quantity in Shopify larger than the single Peasy location quantity.
• If Peasy and Shopify disagree, use Push all to Shopify when Peasy is correct, or Pull all from Shopify when Shopify has the counts you want to adopt.

Related

• Importing from Shopify — The full import flow with staging
• Connecting Shopify — Setting up the connection
• Inventory Overview — How Peasy tracks inventory