Set up Shopify order webhooks

AISA can receive your Shopify orders so that a sale can be tied back to the conversation that led to it. The Sales report reads them. You set this up once, in two places: the Order webhooks card on your Shopify connector, and the Notifications settings of your Shopify admin.

The Shopify pixel reports completed orders too, with less detail. You can use both: each order is counted once, with the webhook's figures. See If the Shopify pixel also reports orders.

Before you startCopy Anchor Link

• A Shopify connector attached to a site. The webhook address belongs to that connector, and orders are recorded against its site.
• Access to your Shopify admin, to read the signing key and create webhooks.
• The Connectors: Edit permission in AISA to save the key. With only Connectors: View, you can read the page but not change it. See Roles.

Set it upCopy Anchor Link

The order test notification does not record a sale. Shopify sends it as a sample order that was never paid, so AISA checks the signature, updates Last verified delivery, and records nothing else.

What AISA recordsCopy Anchor Link

For each paid order:

• The order's identifier, the time it was placed and its currency.
• The order total, in the store's currency. It is the sum of the lines: price times quantity, minus the discount on the line, and minus the tax on the line when your shop prices include tax. Shipping and its tax are not part of it.
• For each line: the line, product and variant identifiers, the SKU, the quantity (as it stands when Shopify announces the payment), the unit price, the discount and the net amount. A line with no product, such as a custom item or a deleted product, is kept like any other.
• Where the order came from (source_name in Shopify, for example web or a draft order), and whether Shopify flagged it as a test order.
• Shopify's cart token, and the conversation key (iadvize_attribution) when the cart carries it, either as a cart attribute or in the landing page address. This is the key that lets a sale be tied to a conversation later.

For each refund: the refund and order identifiers, the time, the currency and the amount of merchandise refunded. The amount is the value of the refunded lines, adjusted by the difference between what Shopify calculated and what it actually refunded. Shipping is left out. A restock that moved no money is recorded with an amount of zero.

For each cancellation: the order identifier, the cancellation time and the test flag. A cancellation carries no amount. It is only recorded for an order that was paid.

AISA does not keep the customer, any address, email address or phone number, or any payment detail. Only the fields listed above are read from a delivery. Anything else Shopify sends, including fields it adds later, is dropped.

Test orders are stored with their test flag, so they can be left out of any figure built from this data later.

Limits to knowCopy Anchor Link

• A failing or deleted webhook means missing orders. Watch Last verified delivery on the connector page. If it stops moving while your store is taking orders, a webhook is broken or gone.
• Check the last order from the API or MCP. Get a site's storefront activity and the MCP tool get_storefront_activity return lastWebhookOrderAt, when the latest order from the webhooks was received. Unlike Last verified delivery, it moves only when an order is recorded: test orders count, the sample order of a test notification does not, nor do refunds and cancellations.
• The date is a clue, not an alarm. AISA does not send an alert. On a quiet store the date can also be old for a good reason.
• An order edited after payment is recorded once. AISA keeps the first version it received and does not amend it. If Shopify announces the same paid order again with a different total, the second copy is not stored.
• Duplicates are harmless. The same delivery received twice, the same refund or the same cancellation, is recorded once.
• A draft order marked as paid is recorded. It arrives as a paid order with its source set to the draft order.
• Only paid orders count. A cancellation for an order that was never paid is ignored.
• A delivery AISA cannot read is acknowledged and dropped. It is not retried, since a retry would give the same result.
• Discount codes are subtracted, and tax comes out after them. For a shop whose prices include VAT, the VAT is taken out of what is left after the discount, so the recorded total excludes both VAT and shipping. ⚠ Automatic discounts, codes limited to some products, and orders shown to the shopper in a different currency than the shop's have not been verified against a real order yet. For such an order, the recorded total may not match what the shopper paid.
• Refunds on shops whose prices include tax can be a little high. A refund is recorded at the amount returned to the customer, tax included, while the order itself is recorded without tax. For example, at a 20 % VAT, a refund of 20.00 is recorded as 20.00, although its share of the recorded revenue would be about 16.67 (20.00 divided by 1.20). A custom amount refunded by hand on such a shop behaved this way in a real test: Shopify sent no tax split, so none is taken out. ⚠ A refund of items on such a shop has not been checked against a real order yet.

If the Shopify pixel also reports ordersCopy Anchor Link

The Shopify pixel sends each completed order from the shopper's browser. With the webhooks set up as well, most orders reach AISA from both. AISA keeps both reports and counts the order once:

• The webhook's figures are used whenever a webhook reported the order: its amount (excluding tax), its time, its test flag and its sales channel. Which report arrived first does not matter.
• The pixel's figures are used only for an order no webhook reported. Such an order has the pixel's limits: an amount that includes tax on a store that shows prices with tax, no test flag, and no check that the payment went through. See Limits of an order only the pixel reported.
• The conversation key is the webhook's. If the webhook's order has none and the pixel's has one, the pixel's key is used.

Refunds and cancellations come from the webhooks only. The pixel sends neither.

Rotate the signing keyCopy Anchor Link

If you rotate the key in Shopify, paste the new one in Signing key right away and save it. Deliveries signed with the old key are rejected while the old key is saved, so Shopify retries them for 4 hours and then drops them.

You can replace the key, but not clear it. The key is stored encrypted and is never shown again: the card only tells you whether one is saved.

When nothing shows upCopy Anchor Link

• No delivery received yet. Check that the key is saved (the card says A key is saved) and matches the one in Settings > Notifications > Webhooks. Check that the webhook URL is the one on the card, character for character, and that the format is JSON. A wrong key, an unknown or deleted connector, and a connector with no key saved all fail the same way: Shopify gets a rejection, and AISA records nothing.
• A date, but orders are missing. The date moves for any correctly signed delivery, including ones AISA then drops. Check that all three webhooks exist, not just the one you tested.
• The page has no Order webhooks card. The card is only shown on Shopify connectors.

Erasing a conversationCopy Anchor Link

When a conversation is deleted, the conversation key is removed from any order that carried it, so the order no longer points to the erased transcript. The order stays, so your store's sales remain complete.