# 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.

---

---

Source: https://docs.durum.ai/en/integrations/shopify