# Shopify subscriptions webhook events

Shopify sends 18 subscription events across contracts, billing attempts, billing cycles and selling plan groups. `subscription_billing_attempts/success` and `subscription_billing_attempts/failure` report the outcome of a charge. Every event here can also reach agents as an MCP event through Hookdeck: [MCP events](https://hookdeck.com/webhooks/shopify/mcp-events).

Agent skill: `npx skills add hookdeck/webhook-skills --skill shopify-webhooks` ([details](https://hookdeck.com/webhooks/shopify/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Shopify's official docs](https://shopify.dev/docs/apps/build/webhooks/delivery-structure).

[Overview](https://hookdeck.com/webhooks/shopify) · [Webhook events (230)](https://hookdeck.com/webhooks/shopify/events) · [MCP events](https://hookdeck.com/webhooks/shopify/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/shopify/verify) · [Production guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/shopify/skill)

## selling_plan_groups/create

Confidence: documented · Schema: from Shopify docs (example)

New selling plan group created

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SellingPlanGroup/1039518909",
  "id": 1039518909,
  "name": "Subscribe & Save",
  "merchant_code": "sub-n-save",
  "admin_graphql_api_app": "gid://shopify/App/2525000003",
  "app_id": null,
  "description": null,
  "options": [ … ],
  "position": null
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/selling-plan-groups-create.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `1039518909` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/selling-plan-groups-create.json)

## selling_plan_groups/delete

Confidence: documented · Schema: from Shopify docs (example)

Selling plan group is deleted

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SellingPlanGroup/1039518911",
  "id": 1039518911
}
```



| Key field | Type | Example |
|---|---|---|
| `id` | integer | `1039518911` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/selling-plan-groups-delete.json)

## selling_plan_groups/update

Confidence: documented · Schema: from Shopify docs (example)

Selling plan group changes

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SellingPlanGroup/1039518915",
  "id": 1039518915,
  "name": "Subscribe & Save",
  "merchant_code": "sub-n-save",
  "admin_graphql_api_app": "gid://shopify/App/2525000003",
  "app_id": null,
  "description": null,
  "options": [ … ],
  "position": null
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/selling-plan-groups-update.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `1039518915` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/selling-plan-groups-update.json)

## subscription_billing_attempts/challenged

Confidence: verified · Schema: from a captured delivery

Bank challenges a subscription charge under 3D Secure

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "id": null,
  "admin_graphql_api_id": null,
  "idempotency_key": "9a453d81-d41d-403e-806f-714dee215ff9",
  "order_id": 1,
  "admin_graphql_api_order_id": "gid://shopify/Order/1",
  "subscription_contract_id": 9998878778,
  "admin_graphql_api_subscription_contract_id": "gid://shopify/SubscriptionContract/9998878778",
  "ready": true
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-attempts-challenged.json)

Seen in a captured delivery: content type `application/json` · API version `2024-10` · headers `content-type`, `user-agent`, `x-shopify-api-version`, `x-shopify-hmac-sha256`, `x-shopify-shop-domain`, `x-shopify-test`, `x-shopify-topic`, `x-shopify-webhook-id`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-attempts-challenged.json)

## subscription_billing_attempts/failure

Confidence: verified · Schema: from a captured delivery

Subscription billing attempt fails

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "id": null,
  "admin_graphql_api_id": null,
  "idempotency_key": "9a453d81-d41d-403e-806f-714dee215ff9",
  "order_id": 1,
  "admin_graphql_api_order_id": "gid://shopify/Order/1",
  "subscription_contract_id": 9998878778,
  "admin_graphql_api_subscription_contract_id": "gid://shopify/SubscriptionContract/9998878778",
  "ready": true
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-attempts-failure.json)

Seen in a captured delivery: content type `application/json` · API version `2024-10` · headers `content-type`, `user-agent`, `x-shopify-api-version`, `x-shopify-hmac-sha256`, `x-shopify-shop-domain`, `x-shopify-test`, `x-shopify-topic`, `x-shopify-webhook-id`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-attempts-failure.json)

## subscription_billing_attempts/success

Confidence: verified · Schema: from a captured delivery

Subscription billing attempt succeeds

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "id": null,
  "admin_graphql_api_id": null,
  "idempotency_key": "9a453d81-d41d-403e-806f-714dee215ff9",
  "order_id": 1,
  "admin_graphql_api_order_id": "gid://shopify/Order/1",
  "subscription_contract_id": 9998878778,
  "admin_graphql_api_subscription_contract_id": "gid://shopify/SubscriptionContract/9998878778",
  "ready": true
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-attempts-success.json)

Seen in a captured delivery: content type `application/json` · API version `2024-10` · headers `content-type`, `user-agent`, `x-shopify-api-version`, `x-shopify-hmac-sha256`, `x-shopify-shop-domain`, `x-shopify-test`, `x-shopify-topic`, `x-shopify-webhook-id`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-attempts-success.json)

## subscription_billing_cycle_edits/create

Confidence: documented · Schema: from Shopify docs (example)

Subscription billing cycle is edited

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "subscription_contract_id": 9998878778,
  "cycle_start_at": "2022-10-01T00:00:00-04:00",
  "cycle_end_at": "2022-11-01T00:00:00-04:00",
  "cycle_index": 1,
  "contract_edit": null,
  "billing_attempt_expected_date": "2022-11-01T00:00:00-04:00",
  "skipped": false,
  "edited": false
}
```



| Key field | Type | Example |
|---|---|---|
| `cycle_start_at` | string | `2022-10-01T00:00:00-04:00` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-cycle-edits-create.json)

## subscription_billing_cycle_edits/delete

Confidence: documented · Schema: from Shopify docs (example)

Subscription billing cycle edit is deleted

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "subscription_contract_id": 9998878778,
  "cycle_start_at": "2022-10-01T00:00:00-04:00",
  "cycle_end_at": "2022-11-01T00:00:00-04:00",
  "cycle_index": 1,
  "contract_edit": null,
  "billing_attempt_expected_date": "2022-11-01T00:00:00-04:00",
  "skipped": false,
  "edited": false
}
```



| Key field | Type | Example |
|---|---|---|
| `cycle_start_at` | string | `2022-10-01T00:00:00-04:00` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-cycle-edits-delete.json)

## subscription_billing_cycle_edits/update

Confidence: documented · Schema: from Shopify docs (example)

Subscription billing cycle edit changes

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "subscription_contract_id": 9998878778,
  "cycle_start_at": "2022-10-01T00:00:00-04:00",
  "cycle_end_at": "2022-11-01T00:00:00-04:00",
  "cycle_index": 1,
  "contract_edit": null,
  "billing_attempt_expected_date": "2022-11-01T00:00:00-04:00",
  "skipped": false,
  "edited": false
}
```



| Key field | Type | Example |
|---|---|---|
| `cycle_start_at` | string | `2022-10-01T00:00:00-04:00` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-cycle-edits-update.json)

## subscription_billing_cycles/skip

Confidence: documented · Schema: from Shopify docs (example)

Subscription billing cycle is skipped

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "subscription_contract_id": 6216896094,
  "cycle_start_at": "2022-10-01T00:00:00-04:00",
  "cycle_end_at": "2022-11-01T00:00:00-04:00",
  "cycle_index": 1,
  "contract_edit": null,
  "billing_attempt_expected_date": "2022-11-01T00:00:00-04:00",
  "skipped": true,
  "edited": true
}
```



| Key field | Type | Example |
|---|---|---|
| `cycle_start_at` | string | `2022-10-01T00:00:00-04:00` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-cycles-skip.json)

## subscription_billing_cycles/unskip

Confidence: documented · Schema: from Shopify docs (example)

Subscription billing cycle is unskipped

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "subscription_contract_id": 9448952952,
  "cycle_start_at": "2022-10-01T00:00:00-04:00",
  "cycle_end_at": "2022-11-01T00:00:00-04:00",
  "cycle_index": 1,
  "contract_edit": null,
  "billing_attempt_expected_date": "2022-11-01T00:00:00-04:00",
  "skipped": false,
  "edited": true
}
```



| Key field | Type | Example |
|---|---|---|
| `cycle_start_at` | string | `2022-10-01T00:00:00-04:00` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-billing-cycles-unskip.json)

## subscription_contracts/activate

Confidence: documented · Schema: from Shopify docs (example)

Subscription contract is activated

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SubscriptionContract/8144725024",
  "id": 8144725024,
  "billing_policy": { … },
  "currency_code": "USD",
  "customer_id": 1,
  "admin_graphql_api_customer_id": "gid://shopify/Customer/1",
  "delivery_policy": { … },
  "status": "active",
  "admin_graphql_api_origin_order_id": "gid://shopify/Order/1",
  "origin_order_id": 1,
  "revision_id": "6734576965"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-activate.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `8144725024` |
| `status` | string | `active` |
| `customer_id` | integer | `1` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-activate.json)

## subscription_contracts/cancel

Confidence: documented · Schema: from Shopify docs (example)

Subscription contract is canceled

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SubscriptionContract/8879965539",
  "id": 8879965539,
  "billing_policy": { … },
  "currency_code": "USD",
  "customer_id": 1,
  "admin_graphql_api_customer_id": "gid://shopify/Customer/1",
  "delivery_policy": { … },
  "status": "cancelled",
  "admin_graphql_api_origin_order_id": "gid://shopify/Order/1",
  "origin_order_id": 1,
  "revision_id": "7654492114"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-cancel.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `8879965539` |
| `status` | string | `cancelled` |
| `customer_id` | integer | `1` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-cancel.json)

## subscription_contracts/create

Confidence: documented · Schema: from Shopify docs (example)

New subscription contract created

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SubscriptionContract/9998878778",
  "id": 9998878778,
  "billing_policy": { … },
  "currency_code": "USD",
  "customer_id": 1,
  "admin_graphql_api_customer_id": "gid://shopify/Customer/1",
  "delivery_policy": { … },
  "status": "active",
  "admin_graphql_api_origin_order_id": "gid://shopify/Order/1",
  "origin_order_id": 1,
  "revision_id": "9998878778"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-create.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `9998878778` |
| `status` | string | `active` |
| `customer_id` | integer | `1` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-create.json)

## subscription_contracts/expire

Confidence: documented · Schema: from Shopify docs (example)

Subscription contract expires

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SubscriptionContract/3504917051",
  "id": 3504917051,
  "billing_policy": { … },
  "currency_code": "USD",
  "customer_id": 1,
  "admin_graphql_api_customer_id": "gid://shopify/Customer/1",
  "delivery_policy": { … },
  "status": "expired",
  "admin_graphql_api_origin_order_id": "gid://shopify/Order/1",
  "origin_order_id": 1,
  "revision_id": "7780548242"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-expire.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `3504917051` |
| `status` | string | `expired` |
| `customer_id` | integer | `1` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-expire.json)

## subscription_contracts/fail

Confidence: documented · Schema: from Shopify docs (example)

Subscription contract fails

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SubscriptionContract/5483094388",
  "id": 5483094388,
  "billing_policy": { … },
  "currency_code": "USD",
  "customer_id": 1,
  "admin_graphql_api_customer_id": "gid://shopify/Customer/1",
  "delivery_policy": { … },
  "status": "failed",
  "admin_graphql_api_origin_order_id": "gid://shopify/Order/1",
  "origin_order_id": 1,
  "revision_id": "8086755151"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-fail.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `5483094388` |
| `status` | string | `failed` |
| `customer_id` | integer | `1` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-fail.json)

## subscription_contracts/pause

Confidence: documented · Schema: from Shopify docs (example)

Subscription contract is paused

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SubscriptionContract/8004927509",
  "id": 8004927509,
  "billing_policy": { … },
  "currency_code": "USD",
  "customer_id": 1,
  "admin_graphql_api_customer_id": "gid://shopify/Customer/1",
  "delivery_policy": { … },
  "status": "paused",
  "admin_graphql_api_origin_order_id": "gid://shopify/Order/1",
  "origin_order_id": 1,
  "revision_id": "1393248951"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-pause.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `8004927509` |
| `status` | string | `paused` |
| `customer_id` | integer | `1` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-pause.json)

## subscription_contracts/update

Confidence: documented · Schema: from Shopify docs (example)

Subscription contract details change

Identified by: x-shopify-topic header · Object: `subscriptions`

```json
{
  "admin_graphql_api_id": "gid://shopify/SubscriptionContract/9998878778",
  "id": 9998878778,
  "billing_policy": { … },
  "currency_code": "USD",
  "customer_id": 1,
  "admin_graphql_api_customer_id": "gid://shopify/Customer/1",
  "delivery_policy": { … },
  "status": "active",
  "admin_graphql_api_origin_order_id": "gid://shopify/Order/1",
  "origin_order_id": 1,
  "revision_id": "9998878778"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-update.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `9998878778` |
| `status` | string | `active` |
| `customer_id` | integer | `1` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/subscription-contracts-update.json)

---

Not affiliated with Shopify. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/shopify.json) · [Report a correction](https://hookdeck.com/contact)
