Subscription webhook notifications

Subscribe to the subscription/update webhook to get notifications about the subscriptions every status change.
You’ll receive a webhook notification to your server indicating the current status.

Note:
The body will include thesubscription object:

Name	Type	Description
planId	string	Unique identifier for the plan
subscriptionId	string	Unique identifier for the subscription
merchantId	string	Identifier for the merchant
vendorId	string	Identifier for the vendor
consumerId	string	Identifier for the consumer who owns the subscription
paymentOption	Object	Payment method contains the PaymentOptionId and type
onboardingLink	number	Subscription cost per billing cycle
currency	string	Currency used for billing
period	number	Billing cycle length
periodUOM	Enum string	Unit of measurement for the billing period
status	Enum string	Current subscription status
nextBillingOn	string	Next billing date
isInBillingRetry	boolean	Indicates if the subscription is in billing retry
nextBillingRetryOn	string	Next billing retry date
billingFailureCount	number	Number of consecutive billing failures
autoRenewal	boolean	Indicates if the subscription auto-renews
trialPeriod	number (optional)	Trial period duration, if applicable
trialPeriodUOM	Enum string (optional)	Unit of measurement for the trial period
trialStart	string (optional)	Trial period start date
trialEnd	string (optional)	Trial period end date
startedOn	string	Subscription start date
endsOn	string	Subscription end date
pausedAt	string	Subscription paused date
createdAt	string	Timestamp when the subscription was created
updatedAt	string	Timestamp when the subscription was last updated
deletedAt	string	Timestamp when the subscription was deleted

Webhook notifications examples

Subscription created

The following webhook notification demonstrates a subscription being created.

JSON

{
    "planId": "6830a082a8eb23a3e2833f2b",
    "subscriptionId": "6830a082a8eb23db16833f2c",
    "vendorId": "6830a082a8eb230740833f2d",
    "consumerId": "6830a082a8eb23ad6c833f2e",
    "paymentOption": {
        "id": "6830a082a8eb23a211833f2f"
    },
    "endsOn": "2025-05-23T16:21:22.750Z",
    "createdAt": "2025-05-23T16:21:22.750Z",
    "updatedAt": "2025-05-23T16:21:22.750Z",
    "deletedAt": "2025-05-23T16:21:22.750Z",
    "nextBillingOn": "2025-05-23T16:21:22.750Z",
    "nextBillingRetryOn": "2025-05-23T16:21:22.750Z",
    "startedOn": "2025-05-23T16:21:22.750Z",
    "price": 99.99,
    "currency": "GBP",
    "period": 12,
    "periodUOM": "month",
    "status": "enabled",
    "isInBillingRetry": false,
    "billingFailureCount": 0,
    "trialPeriod": 0,
    "rampIntervals": [],
    "autoRenewal": false,
    "merchantId": "66d58bd06098898a5de10bdc",
    "pricingModel": "fixed"
}

Subscription updated

The following webhook notification example demonstrates a subscription being updated.

JSON

{
    "planId": "6830a0c5a8eb238870833f30",
    "subscriptionId": "6830a0c5a8eb2331d9833f31",
    "vendorId": "6830a0c5a8eb238c2a833f32",
    "consumerId": "6830a0c5a8eb232a4b833f33",
    "paymentOption": {
        "id": "6830a0c5a8eb236c5c833f34"
    },
    "endsOn": "2025-05-23T16:22:29.834Z",
    "createdAt": "2025-05-23T16:22:29.834Z",
    "updatedAt": "2025-05-23T16:22:29.834Z",
    "deletedAt": "2025-05-23T16:22:29.834Z",
    "nextBillingOn": "2025-05-23T16:22:29.834Z",
    "nextBillingRetryOn": "2025-05-23T16:22:29.834Z",
    "startedOn": "2025-05-23T16:22:29.834Z",
    "price": 99.99,
    "currency": "GBP",
    "period": 12,
    "periodUOM": "month",
    "status": "enabled",
    "isInBillingRetry": false,
    "billingFailureCount": 0,
    "trialPeriod": 0,
    "rampIntervals": [],
    "autoRenewal": false,
    "merchantId": "66d58bd06098898a5de10bdc",
    "pricingModel": "fixed"
}