Shopify

What It Does

Shopify sends your paid orders (sales) and your refunds to DURUM.ai in real time. You connect in one click from your store (OAuth): DURUM.ai registers the needed webhooks itself, there is no URL to paste.

DURUM.ai tracks your store from the moment you connect. No import of past orders.

Before You Start

• A Shopify store and an owner or staff account allowed to install an app.
• The store's .myshopify.com address (for example mystore.myshopify.com). It is in the Shopify admin, Settings, Domains.
• Access to DURUM.ai with an agency or client role.

Access requested from Shopify (read only): read_orders, read_products, read_customers, read_checkouts, read_analytics, read_reports, read_fulfillments, read_inventory. DURUM.ai writes nothing to your store.

Step-by-Step Connection

1. In DURUM.ai, go to Settings then Integrations.
2. On the Shopify card (E-commerce category), click Connect.
3. In the Your store URL field, enter your store's .myshopify.com subdomain, for example mystore.myshopify.com. The short form mystore is accepted. The store's custom domain (www.mystore.com) is not accepted.
4. Click Connect. You are redirected to Shopify.
5. Sign in to the store if needed and click Install to authorize the DURUM.ai app.
6. You come back to DURUM.ai with the message "Shopify connected". DURUM.ai has registered five webhooks in the store: orders/create, orders/paid, orders/cancelled, refunds/create and app/uninstalled, all pointing to https://app.durum.ai/api/webhook/shopify. These webhooks are created by the app: there is nothing to set up in Shopify.

Verify It Works

1. Place a paid test order in your store (test mode of your payment gateway, or a real order).
2. Wait 30 seconds.
3. In DURUM.ai, open Data Logs: a sale event with source shopify should appear with status processed.
4. Refund that test order in Shopify: a refund event should follow, with a negative amount.

Captured Events

Shopify side	DURUM.ai event	What it feeds
orders/paid	sale	Sales. Amount = total_price in the order currency, contact = customer email, customer name, product = title of the first line item, reference = order ID. Date = the order's processed_at.
orders/create with financial_status equal to paid	sale	Sales (same content as above). An order created but not yet paid is ignored with reason order_not_paid_yet, then counted when orders/paid arrives.
orders/cancelled	none	Received then ignored. A cancellation creates no event.
refunds/create	refund	Refunds. Negative amount = sum of the refund's transactions (partial refunds included). Email and name taken from the original order.
app/uninstalled	none	The connection switches to status revoked and the sync stops.

An order is only counted once: DURUM.ai deduplicates by order ID (and by refund ID for refunds). A duplicate shows in Data Logs with status ignored.

Troubleshooting

Problem	Solution
"Invalid format. Expected example: mystore.myshopify.com"	Enter the .myshopify.com address, not the store's custom domain.
No event for an order	Check that the order is paid (financial_status equal to paid). An order awaiting payment is only counted once paid.
Status error with message Invalid HMAC	The webhook signature does not match the DURUM.ai app installed in the store. Disconnect then reconnect the integration to recreate the webhooks.
Response unknown_client in Data Logs	DURUM.ai could not tie the store to your account. Disconnect then reconnect the integration.
Status ignored on an order	Duplicate (order already counted) or unpaid order. No action needed.
The card shows the connection as revoked	The app was uninstalled from Shopify. Click Connect to reinstall it.
Refund without an email	The original order was placed before the connection: DURUM.ai does not know it. The refund is still recorded.

FAQ

Does DURUM.ai import my past orders?

No. Tracking starts at connection. An order placed before the connection does not show up, even if it is paid later.

Can I connect two stores?

One Shopify connection per client account. For a second store, use a second client account in DURUM.ai.

How are partial refunds handled?

The recorded amount is the actual sum of the refund's transactions, as a negative value. A partial refund only subtracts its own amount.

What happens on disconnect?

DURUM.ai only removes the webhooks pointing to app.durum.ai. Webhooks from your other apps (Make, Zapier, etc.) are never touched.

Which currency?

The amount is recorded in the order currency as Shopify sends it.

---