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 →
selling_plan_groups/create
documented from Shopify docs (example)
selling_plan_groups/create New selling plan group created
Identified by x-shopify-topic header
Resource subscriptions
{
"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
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 1039518909 |
Full schema: 32 fields.
From Shopify docs
-
Content type
application/json
selling_plan_groups/delete
documented from Shopify docs (example)
selling_plan_groups/delete Selling plan group is deleted
Identified by x-shopify-topic header
Resource subscriptions
{
"admin_graphql_api_id": "gid://shopify/SellingPlanGroup/1039518911",
"id": 1039518911
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 1039518911 |
Full schema: 2 fields.
From Shopify docs
-
Content type
application/json
selling_plan_groups/update
documented from Shopify docs (example)
selling_plan_groups/update Selling plan group changes
Identified by x-shopify-topic header
Resource subscriptions
{
"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
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 1039518915 |
Full schema: 32 fields.
From Shopify docs
-
Content type
application/json
subscription_billing_attempts/challenged
verified from a captured delivery
subscription_billing_attempts/challenged Bank challenges a subscription charge under 3D Secure
Identified by x-shopify-topic header
Resource subscriptions
{
"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
} 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
subscription_billing_attempts/failure
verified from a captured delivery
subscription_billing_attempts/failure Subscription billing attempt fails
Identified by x-shopify-topic header
Resource subscriptions
{
"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
} 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
subscription_billing_attempts/success
verified from a captured delivery
subscription_billing_attempts/success Subscription billing attempt succeeds
Identified by x-shopify-topic header
Resource subscriptions
{
"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
} 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
subscription_billing_cycle_edits/create
documented from Shopify docs (example)
subscription_billing_cycle_edits/create Subscription billing cycle is edited
Identified by x-shopify-topic header
Resource subscriptions
{
"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 fields
| Field | Type | Example |
|---|---|---|
cycle_start_at | string | 2022-10-01T00:00:00-04:00 |
Full schema: 8 fields.
From Shopify docs
-
Content type
application/json
subscription_billing_cycle_edits/delete
documented from Shopify docs (example)
subscription_billing_cycle_edits/delete Subscription billing cycle edit is deleted
Identified by x-shopify-topic header
Resource subscriptions
{
"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 fields
| Field | Type | Example |
|---|---|---|
cycle_start_at | string | 2022-10-01T00:00:00-04:00 |
Full schema: 8 fields.
From Shopify docs
-
Content type
application/json
subscription_billing_cycle_edits/update
documented from Shopify docs (example)
subscription_billing_cycle_edits/update Subscription billing cycle edit changes
Identified by x-shopify-topic header
Resource subscriptions
{
"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 fields
| Field | Type | Example |
|---|---|---|
cycle_start_at | string | 2022-10-01T00:00:00-04:00 |
Full schema: 8 fields.
From Shopify docs
-
Content type
application/json
subscription_billing_cycles/skip
documented from Shopify docs (example)
subscription_billing_cycles/skip Subscription billing cycle is skipped
Identified by x-shopify-topic header
Resource subscriptions
{
"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 fields
| Field | Type | Example |
|---|---|---|
cycle_start_at | string | 2022-10-01T00:00:00-04:00 |
Full schema: 8 fields.
From Shopify docs
-
Content type
application/json
subscription_billing_cycles/unskip
documented from Shopify docs (example)
subscription_billing_cycles/unskip Subscription billing cycle is unskipped
Identified by x-shopify-topic header
Resource subscriptions
{
"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 fields
| Field | Type | Example |
|---|---|---|
cycle_start_at | string | 2022-10-01T00:00:00-04:00 |
Full schema: 8 fields.
From Shopify docs
-
Content type
application/json
subscription_contracts/activate
documented from Shopify docs (example)
subscription_contracts/activate Subscription contract is activated
Identified by x-shopify-topic header
Resource subscriptions
{
"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"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 8144725024 |
status | string | active |
customer_id | integer | 1 |
Full schema: 17 fields.
From Shopify docs
-
Content type
application/json
subscription_contracts/cancel
documented from Shopify docs (example)
subscription_contracts/cancel Subscription contract is canceled
Identified by x-shopify-topic header
Resource subscriptions
{
"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"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 8879965539 |
status | string | cancelled |
customer_id | integer | 1 |
Full schema: 17 fields.
From Shopify docs
-
Content type
application/json
subscription_contracts/create
documented from Shopify docs (example)
subscription_contracts/create New subscription contract created
Identified by x-shopify-topic header
Resource subscriptions
{
"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"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 9998878778 |
status | string | active |
customer_id | integer | 1 |
Full schema: 17 fields.
From Shopify docs
-
Content type
application/json
subscription_contracts/expire
documented from Shopify docs (example)
subscription_contracts/expire Subscription contract expires
Identified by x-shopify-topic header
Resource subscriptions
{
"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"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 3504917051 |
status | string | expired |
customer_id | integer | 1 |
Full schema: 17 fields.
From Shopify docs
-
Content type
application/json
subscription_contracts/fail
documented from Shopify docs (example)
subscription_contracts/fail Subscription contract fails
Identified by x-shopify-topic header
Resource subscriptions
{
"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"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 5483094388 |
status | string | failed |
customer_id | integer | 1 |
Full schema: 17 fields.
From Shopify docs
-
Content type
application/json
subscription_contracts/pause
documented from Shopify docs (example)
subscription_contracts/pause Subscription contract is paused
Identified by x-shopify-topic header
Resource subscriptions
{
"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"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 8004927509 |
status | string | paused |
customer_id | integer | 1 |
Full schema: 17 fields.
From Shopify docs
-
Content type
application/json
subscription_contracts/update
documented from Shopify docs (example)
subscription_contracts/update Subscription contract details change
Identified by x-shopify-topic header
Resource subscriptions
{
"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"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 9998878778 |
status | string | active |
customer_id | integer | 1 |
Full schema: 17 fields.
From Shopify docs
-
Content type
application/json
Route Shopify events by type.
Event Gateway receives every Shopify delivery and filters and routes it by event type, so each service gets only the events it handles.