> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/collect-data/shopify/server-events/webhook-events.md).

# Webhook events reference

Once you've set up [server events](/collect-data/shopify/server-events.md), Chord subscribes your store to the Shopify webhook topics below and turns each one into a Chord event. This page lists what each topic produces, and the customer properties Chord adds that Shopify's payloads don't include.

Subscription events don't come through these webhooks. Shopify only sends subscription webhooks to the app that created the subscription, so they're sent with Shopify Flow instead. See [Subscription events](/collect-data/shopify/server-events/subscription-events.md).

## Topics and events

Order and checkout events (Chord adds [customer properties](#customer-properties)):

* `orders/create` → [Order Completed](/collect-data/tracking-plan/order-completed.md)
* `orders/fulfilled` → Order Fulfilled
* `orders/cancelled` → [Order Cancelled](/collect-data/tracking-plan/order-cancelled.md)
* `refunds/create` → [Order Refunded](/collect-data/tracking-plan/order-refunded.md)
* `checkouts/create` → [Checkout Started](/collect-data/tracking-plan/checkout-started.md)

Fulfillment, risk and housekeeping events (no customer properties):

* `fulfillments/create` → Fulfillment Created
* `fulfillments/update` → Fulfillment Updated
* `orders/risk_assessment_changed` → Order Risk Assessed
* `orders/delete` → Order Deleted
* `customers/delete` → Customer Deleted
* `customers/merge` → Customer Merged
* `locations/delete` → Location Deleted
* `products/delete` → Product Deleted

## Customer properties

Shopify removed lifetime customer statistics, such as `orders_count`, from webhook payloads in its 2025-01 API version. To fill the gap, Chord looks up the customer through the Shopify Admin API and adds these properties to every order and checkout event that carries a customer ID:

* **`repeat`** (boolean): whether the customer had ordered before this event.
* **`is_new_customer`** (number): the same signal as `repeat`, inverted, as `0` or `1`.
* **`customer_order_count`** (number): lifetime order count as Shopify reports it.
* **`customer_lifetime_revenue`** (number): total the customer has spent.
* **`customer_lifetime_revenue_currency`** (string): ISO currency code for `customer_lifetime_revenue`.
* **`customer_since`** (string): date and time the customer record was created in Shopify.
* **`customer_tags`** (string array): tags applied to the customer in Shopify.
* **`customer_subscriber_status`** (string): product subscriber status, such as `ACTIVE` or `NEVER_SUBSCRIBED`.

`repeat` and `is_new_customer` say the same thing in two shapes, so each destination can read the convention it already expects.

### New versus returning

`repeat` and `is_new_customer` answer one question: had this customer ordered before the event being reported?

Shopify counts an order against the customer as soon as it's created, so an order webhook reports a `customer_order_count` that already includes that order. Chord leaves that order out when it sets the flags. A first-time buyer's Order Completed arrives as:

```json
{
  "repeat": false,
  "is_new_customer": 1,
  "customer_order_count": 1
}
```

A returning customer placing their third order arrives as:

```json
{
  "repeat": true,
  "is_new_customer": 0,
  "customer_order_count": 3
}
```

Checkout Started has no order in it, so no adjustment is made. `customer_order_count` is always the raw figure from Shopify.

### When properties are missing

Customer properties need the `read_customers` scope on the Chord Webhook Events app, which the [server events setup](/collect-data/shopify/server-events.md#step-2-configure-access-scopes) includes.

{% hint style="warning" %}
Customer properties are added on a best-effort basis. If the lookup fails, for example because of a missing scope or a Shopify outage, Chord still delivers the event, just without these properties. If they're missing from your events, check the app's scopes first.
{% endhint %}

Chord reads these values from Shopify when it processes the event. If an event is retried after a delivery failure, it gets the customer's values at retry time. That only differs from the first attempt if the customer's order history changed in between.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/collect-data/shopify/server-events/webhook-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.