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)

New selling plan group created

Identified by x-shopify-topic header Resource subscriptions

shopify-selling-plan-groups-create.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
}

Key fields

Field Type Example
id integer 1039518909

Full schema: 32 fields.

From Shopify docs

  • Content type application/json

Send example to Inspect → View as JSON

selling_plan_groups/delete

documented from Shopify docs (example)

Selling plan group is deleted

Identified by x-shopify-topic header Resource subscriptions

shopify-selling-plan-groups-delete.json
{
  "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

Send example to Inspect → View as JSON

selling_plan_groups/update

documented from Shopify docs (example)

Selling plan group changes

Identified by x-shopify-topic header Resource subscriptions

shopify-selling-plan-groups-update.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
}

Key fields

Field Type Example
id integer 1039518915

Full schema: 32 fields.

From Shopify docs

  • Content type application/json

Send example to Inspect → View as JSON

subscription_billing_attempts/challenged

verified from a captured delivery

Bank challenges a subscription charge under 3D Secure

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-attempts-challenged.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
}

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

Send example to Inspect → View as JSON

subscription_billing_attempts/failure

verified from a captured delivery

Subscription billing attempt fails

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-attempts-failure.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
}

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

Send example to Inspect → View as JSON

subscription_billing_attempts/success

verified from a captured delivery

Subscription billing attempt succeeds

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-attempts-success.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
}

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

Send example to Inspect → View as JSON

subscription_billing_cycle_edits/create

documented from Shopify docs (example)

Subscription billing cycle is edited

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-cycle-edits-create.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 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

Send example to Inspect → View as JSON

subscription_billing_cycle_edits/delete

documented from Shopify docs (example)

Subscription billing cycle edit is deleted

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-cycle-edits-delete.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 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

Send example to Inspect → View as JSON

subscription_billing_cycle_edits/update

documented from Shopify docs (example)

Subscription billing cycle edit changes

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-cycle-edits-update.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 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

Send example to Inspect → View as JSON

subscription_billing_cycles/skip

documented from Shopify docs (example)

Subscription billing cycle is skipped

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-cycles-skip.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 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

Send example to Inspect → View as JSON

subscription_billing_cycles/unskip

documented from Shopify docs (example)

Subscription billing cycle is unskipped

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-billing-cycles-unskip.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 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

Send example to Inspect → View as JSON

subscription_contracts/activate

documented from Shopify docs (example)

Subscription contract is activated

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-contracts-activate.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"
}

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

Send example to Inspect → View as JSON

subscription_contracts/cancel

documented from Shopify docs (example)

Subscription contract is canceled

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-contracts-cancel.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"
}

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

Send example to Inspect → View as JSON

subscription_contracts/create

documented from Shopify docs (example)

New subscription contract created

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-contracts-create.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"
}

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

Send example to Inspect → View as JSON

subscription_contracts/expire

documented from Shopify docs (example)

Subscription contract expires

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-contracts-expire.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"
}

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

Send example to Inspect → View as JSON

subscription_contracts/fail

documented from Shopify docs (example)

Subscription contract fails

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-contracts-fail.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"
}

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

Send example to Inspect → View as JSON

subscription_contracts/pause

documented from Shopify docs (example)

Subscription contract is paused

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-contracts-pause.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"
}

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

Send example to Inspect → View as JSON

subscription_contracts/update

documented from Shopify docs (example)

Subscription contract details change

Identified by x-shopify-topic header Resource subscriptions

shopify-subscription-contracts-update.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"
}

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

Send example to Inspect → View as 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.

Not affiliated with Shopify. Facts are compiled from public sources and linked inline.