> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abconvert.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Webhooks — ABConvert API

> Shopify webhooks ABConvert registers automatically: orders, inventory, shop changes, theme publishing, and app removal — no setup required from you.

<Note>
  **Preview — this page is an early draft.** We're still verifying the API reference against the current endpoints. Fields, response shapes, and examples may change before this section is marked stable. Follow [PRO-1459](https://linear.app/abconvert/issue/PRO-1459) or ask in `#abconvert-dev` if you're integrating against this today.
</Note>

When you install ABConvert, the app automatically registers a set of Shopify webhook subscriptions. These webhooks keep ABConvert in sync with your store's data without any manual configuration. You do not need to set up or manage these webhooks yourself.

All webhook payloads are delivered by Shopify to ABConvert's internal webhook handler at:

```
POST /api/webhooks
```

ABConvert verifies the HMAC signature on every incoming webhook payload. Successfully processed webhooks return `200 OK` with an empty body.

***

## APP\_UNINSTALLED

**Triggered when:** A merchant removes ABConvert from their Shopify store.

**What ABConvert does:**

When you uninstall the app, ABConvert receives this webhook and immediately:

* Stops all active experiments and removes associated Shopify scripts, metafields, and variant duplicates.
* Deregisters all Shopify Functions (cart transforms, delivery customizations, payment customizations) that ABConvert deployed.
* Clears the store's configuration from ABConvert's systems.

This ensures no ABConvert code remains active on your storefront after uninstallation.

**Shopify payload:** Standard app uninstall payload containing the shop domain and ID.

***

## ORDERS\_CREATE

**Triggered when:** A new order is placed in your Shopify store.

**What ABConvert does:**

ABConvert uses this webhook to record completed order data against the experiment sessions it tracked through the funnel. When an order arrives:

1. ABConvert matches the order's line items and checkout session to experiment assignments stored in cart attributes.
2. Revenue and order count are attributed to the correct test group.
3. The data flows into the experiment analytics so you see accurate conversion and revenue metrics.

<Note>
  Order attribution relies on cart attributes that the ABConvert tracking script writes during the session. If a visitor disabled cookies or the tracking script was blocked, the order may not be attributed to an experiment.
</Note>

**Shopify payload fields used:**

| Field                     | Description                 |
| ------------------------- | --------------------------- |
| `id`                      | Shopify order ID            |
| `line_items[].product_id` | Products in the order       |
| `line_items[].variant_id` | Specific variants ordered   |
| `total_price`             | Order revenue for analytics |

***

## ORDERS\_EDITED

**Triggered when:** An existing order is modified (items added, removed, or refunded).

**What ABConvert does:**

When an order is edited after placement, ABConvert updates the stored revenue and line-item data to reflect the change. This keeps experiment revenue metrics accurate when merchants issue partial refunds or edit orders after the fact.

**Shopify payload:** Standard Shopify order payload with the updated order data and a record of the changes applied.

***

## INVENTORY\_LEVELS\_UPDATE

**Triggered when:** Inventory levels change for any product variant in your store.

**What ABConvert does:**

For V1 price tests, ABConvert uses this webhook to sync inventory levels across duplicate product variants. When stock changes on your original variant, the update is automatically applied to all duplicate variants created for the same experiment, so every test group sees accurate inventory counts.

**Shopify payload fields used:**

| Field               | Description                             |
| ------------------- | --------------------------------------- |
| `inventory_item_id` | Identifies the variant's inventory item |
| `location_id`       | The fulfillment location affected       |
| `available`         | Updated available inventory count       |

***

## SHOP\_UPDATE

**Triggered when:** Your Shopify store settings change — for example, the store name, primary domain, currency, or timezone.

**What ABConvert does:**

ABConvert keeps a local copy of your shop's core attributes for use in experiment configuration and analytics. When Shopify sends a `SHOP_UPDATE` webhook, ABConvert refreshes this cached data to ensure experiment settings (such as currency display and timezone-based scheduling) stay consistent with your store.

**Shopify payload fields used:**

| Field    | Description               |
| -------- | ------------------------- |
| `id`     | Shopify shop ID           |
| `name`   | Store display name        |
| `domain` | Primary storefront domain |

***

## THEMES\_PUBLISH

**Triggered when:** You publish a new or updated theme in your Shopify store.

**What ABConvert does:**

Publishing a new theme can break active experiment scripts and theme-level modifications that ABConvert injected into your previous theme. When ABConvert receives a `THEMES_PUBLISH` event, it:

* Checks whether any active experiments depend on theme-level scripts or blocks.
* Reinstalls or reactivates ABConvert's theme app blocks in the newly published theme where possible.
* Flags experiments that may require manual attention if the new theme does not include the required ABConvert blocks.

**Shopify payload fields used:**

| Field  | Description                                             |
| ------ | ------------------------------------------------------- |
| `id`   | Shopify theme ID                                        |
| `name` | Theme name                                              |
| `role` | `main` when the theme is the published storefront theme |

<Warning>
  If you publish a new theme without first enabling the ABConvert theme app extension in the new theme's editor, active content and template experiments may stop serving variants. ABConvert will alert you in the dashboard when this is detected.
</Warning>

***

## Summary

| Webhook                   | Trigger                    | ABConvert action                                    |
| ------------------------- | -------------------------- | --------------------------------------------------- |
| `APP_UNINSTALLED`         | App removed from store     | Clean up all scripts, variants, and metafields      |
| `ORDERS_CREATE`           | New order placed           | Record order revenue against experiment test groups |
| `ORDERS_EDITED`           | Order modified or refunded | Update attributed revenue in experiment analytics   |
| `INVENTORY_LEVELS_UPDATE` | Inventory changes          | Track stock levels for experiment data quality      |
| `SHOP_UPDATE`             | Store settings changed     | Refresh cached shop attributes                      |
| `THEMES_PUBLISH`          | New theme published        | Reactivate theme blocks for active experiments      |

All webhooks are registered and managed automatically by ABConvert. No configuration is required on your part.