> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ordergroove.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server. # Subscription Events These events fire on the subscription object. To receive them, register the `subscription.*` pattern — or any individual event below — against a webhook target. See [Configure Webhooks via API](/data/configure-webhooks) for how to create a target and define filters. --- ## Event types | Event | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subscription.create` | Triggered whenever the customer creates a subscription. This event can only be triggered once for a subscription. This event is not triggered when creation is from your Ordergroove Admin. | | `subscription.cancel` | Triggered whenever a subscription is cancelled. This event can be triggered more than once for a subscription. | | `subscription.sku_swap` | Triggered when the product associated with a subscription is changed. This event can be triggered more than once for a subscription. | | `subscription.reactivate` | — | | `subscription.change_frequency` | Triggered when the subscription's delivery frequency is modified. This event can be triggered more than once for a subscription. | | `subscription.change_components` | For subscriptions associated with bundles, this is triggered when a product is updated, added, or removed from the list of bundle components of the subscription. This event can be triggered more than once for a subscription. | | `subscription.change_quantity` | Triggered when the subscription's quantity is modified. This event can be triggered more than once for a subscription. | | `subscription.change_shipping_address` | Triggered when a subscription's shipping address is set. This event can be triggered more than once for a subscription. | | `subscription.change_payment` | Triggered when a subscription's payment is set. This event can be triggered more than once for a subscription. | | `subscription.change_live` | Triggered when a cancelled subscription is reactivated. This event can be triggered more than once for a subscription. | | `subscription.*` | Matches every event in this family. | --- ## Payload | Name | Type | Description | Example | | :----------------------------------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | | `id` | str | Identifier of the event | "mmmm4444nnnn3333pppp" | | `type` | str | The type of event that occurred | See below for full list of event types | | `created` | int | Time since epoch when the event occurred | 1622589211 | | `data` | object | Event data object | See JSON below | | `data.object.type` | str | Resource type of event | "Subscription" | | `data.object.merchant` | str | Identifier of merchant | "aaaa1111bbbb2222cccc" | | `data.object.public_id` | str | Public ID of resource. Should be used to retrieve additional resource object data via OG API if necessary. | "zzzz9999yyyy8888xxxx" | | `data.object.customer` | str | The `merchant_user_id` — the ID from the merchant system, not our internal public ID | "h183738" | | `data.object.product` | str | The external product ID from the merchant's system | "SKUabc" | | `data.object.components` | array | List of objects representing the bundle components/products | `[{"product": "product_1", "public_id": "...", "quantity": 1}]` | | `data.object.prepaid_subscription_context` | object | Prepaid information returned only if prepaid is enabled | `{"prepaid_orders_remaining": 0, "prepaid_orders_per_billing": 3, "renewal_behavior": "autorenew", ...}` or `null` | | `data.object.extra_data` | object | Key/value store for any extra information | `{"some": "extra", "fields": "here"}` | | `data.object.quantity` | int | Number of items | 1 | | `data.object.price` | str | Price of the subscription when leveraging price lock feature | "12.99" | | `data.object.frequency_days` | int | Order placement interval in days | 30 | | `data.object.reminder_days` | int | Days before order placement to send email reminder (minimum of 5) | 5 | | `data.object.every` | int | Number of periods | 1 | | `data.object.every_period` | int | Type of period enum. Options: 1, 2, 3 | 3 | | `data.object.every_period_display` | str | Readable version of period enum. Options: "Days", "Weeks", "Months" | "Months" | | `data.object.cancelled` | int | Unix timestamp of when the subscription was cancelled, if no longer active | 1301325188 | | `data.object.cancel_reason` | str | Pipe-delimited cancel reason code and cancel reason details | "4\|Overstocked" | | `data.object.cancel_reason_code` | int | Code ID of the cancel reason | 4 | | `data.object.session_id` | str | Session ID, obtained from `og_session_id` cookie | "aaaa1111bbbb2222cccc.450125.1299622365" | | `data.object.merchant_order_id` | str | Order ID in your system, corresponding to the checkout that created the subscription | "12345678" | | `data.object.live` | bool | Whether the subscription is active. `true` means the customer wants to continue receiving the product; `false` means they do not. | true | | `data.object.external_id` | str | External representation of the subscription in your system. For Shopify integrations, this is the Shopify contract ID. | "external-identifier" | | `data.object.created` | int | Unix timestamp when the subscription was created | 1300375961 | | `data.object.start_date` | str | Date the subscription started. Format: "YYYY-MM-DD" | "2021-03-25" | | `data.object.offer` | str | Offer record ID | "a748aa648ac811e8af3bbc764e106cf4" | | `data.object.payment` | str | Payment record ID | "070001bc02fd11e99542bc764e1043b0" | | `data.object.shipping_address` | str | Shipping address record ID | "66c25cd0564011e9abc5bc764e107990" | | `data.object.updated` | int | Unix timestamp when the subscription was updated | 1300375961 | **`Example Data`** ```json title="Example Data" { "id": "mmmm4444nnnn3333pppp", "type": "subscription.create", "created": 1622589211, "data": { "object": { "type": "subscription", "merchant": "aaaa1111bbbb2222cccc", "public_id": "zzzz9999yyyy8888xxxx", "customer": "m1234576", "product": "SKUabc", "components": [ {"product": "product_1"}, {"product": "product_2"} ], "extra_data": {}, "quantity": 1, "price": null, "frequency_days": 56, "reminder_days": 10, "every": 2, "every_period": 2, "every_period_display": "Weeks", "cancelled": 1301325188, "cancel_reason": "", "cancel_reason_code": null, "session_id": "aaaa1111bbbb2222cccc.450125.1299622365", "merchant_order_id": "12345678", "live": true, "external_id": null, "created": 1300375961, "start_date": "2021-03-25", "offer": "a748aa648ac811e8af3bbc764e106cf4", "payment": "070001bc02fd11e99542bc764e1043b0", "shipping_address": "66c25cd0564011e9abc5bc764e107990", "updated": 1300375961 } } } ```