Ordergroove Developer Documentation

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 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

{
  "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
    }
  }
}