SubscriptionsImplementation Methods

Subscription Webhooks

Use this documentation to listen to webhook events specific to subscription lifecycle and billing.

Webhooks may be sent more than once—add deduplication logic to prevent duplicate events.

✅ Event Types

Subscription webhooks fall into two categories:

  • Subscription category — lifecycle events unique to subscriptions (created, canceled, expired, failure)
  • Purchase category — standard payment events that also fire on subscription billing cycles, and include a subscription object in the payload
Event TypeCategoryDescription
Subscription CreatedSubscriptionA subscription was purchased and activated for the first time.
Subscription CanceledSubscriptionA subscription was canceled by the customer or merchant. Includes a reason field.
Subscription ExpiredSubscriptionThe subscription can no longer be renewed (e.g. plan deactivated or max duration reached).
Subscription FailureSubscriptionA renewal payment failed, preventing the subscription from being created or renewed.
SettledPurchaseA subscription billing payment completed successfully. Includes a subscription object.
Card Payment AuthorizedPurchaseA subscription renewal card was authorized but not yet captured. Includes a subscription object.
Card Payment DeclinedPurchaseA subscription renewal card was declined by the issuing bank.

Sample Webhook Payloads

Subscription Lifecycle Events

These events use the Subscription category and contain subscription-specific data.

Subscription Created
1// Sent when a customer pays for a subscription for the first time
2{
3  "eventType": "Subscription Created",
4  "category": "Subscription",
5  "created": "2025-04-28T20:28:08.289Z",
6  "data": {
7    "planCode": "music_access",
8    "planName": "creator1234",
9    "subscriptionId": "680fe4d832ddccc1ee91885e",
10    "customerId": "78C3dn4yUJST9pcX9GtA3yWBcKUCjDw1RWqw1MLpoUDh",
11    "amount": {
12      "cents": 500,
13      "currency": "USD"
14    },
15    "interval": "Monthly",
16    "fundingMethod": "Card",
17    "webhookInfo": {
18      "item": "sword"
19    }
20  }
21}
Subscription Canceled
1// Sent when a customer or merchant cancels a subscription
2{
3  "eventType": "Subscription Canceled",
4  "category": "Subscription",
5  "created": "2025-04-28T20:33:05.322Z",
6  "data": {
7    "planCode": "music_access",
8    "planName": "creator1234",
9    "subscriptionId": "67d07938a899c293e0ae2147",
10    "customerId": "67Lj6ZcTRDtWT3Rx4KWAdLUrHKeLcycBzwvhzGowrHjx",
11    "amount": {
12      "cents": 500,
13      "currency": "USD"
14    },
15    "interval": "Monthly",
16    "fundingMethod": "Card",
17    "webhookInfo": {
18      "item": "sword"
19    },
20    "reason": "Customer has canceled subscription"
21  }
22}
Subscription Expired
1// Sent when a subscription can no longer be renewed
2{
3  "eventType": "Subscription Expired",
4  "category": "Subscription",
5  "created": "2025-04-28T20:35:00.000Z",
6  "data": {
7    "planCode": "music_access",
8    "planName": "creator1234",
9    "subscriptionId": "67d07938a899c293e0ae2147",
10    "customerId": "67Lj6ZcTRDtWT3Rx4KWAdLUrHKeLcycBzwvhzGowrHjx",
11    "amount": {
12      "cents": 500,
13      "currency": "USD"
14    },
15    "interval": "Monthly",
16    "fundingMethod": "Card",
17    "webhookInfo": {
18      "item": "sword"
19    },
20    "reason": "Subscription has expired"
21  }
22}
Subscription Failure
1// Sent when a renewal payment fails and the subscription cannot be renewed
2{
3  "eventType": "Subscription Failure",
4  "category": "Subscription",
5  "created": "2025-04-28T20:36:00.000Z",
6  "data": {
7    "planCode": "music_access",
8    "planName": "creator1234",
9    "subscriptionId": "67d07938a899c293e0ae2147",
10    "customerId": "67Lj6ZcTRDtWT3Rx4KWAdLUrHKeLcycBzwvhzGowrHjx",
11    "amount": {
12      "cents": 500,
13      "currency": "USD"
14    },
15    "interval": "Monthly",
16    "fundingMethod": "Card",
17    "webhookInfo": {
18      "item": "sword"
19    }
20  }
21}

Subscription Payment Events

These events use the Purchase category and include a subscription object containing the full subscription and plan details.

Settled
1// Sent when a subscription billing payment completes; funds are in your settlement wallet
2{
3  "eventType": "Settled",
4  "category": "Purchase",
5  "created": "2025-04-28T20:28:10.894Z",
6  "data": {
7    "id": "db746ccf-6dce-4019-b34b-b35a957cb5aa",
8    "signature": "5utLY7sWhJiXtRiw8jQ3thqyubcmsPh9rN9rWpsU4i3jw9mwwbkYchDpEEoZ3sTF8DosiwffQHbEXP5Zk5RE1fQo",
9    "webhookInfo": {
10      "item": "sword"
11    },
12    "subtotal": {
13      "cents": 500,
14      "currency": "USD"
15    },
16    "fees": {
17      "cents": 46,
18      "currency": "USD"
19    },
20    "gasFees": {
21      "cents": 0,
22      "currency": "USD"
23    },
24    "chargebackProtectionFees": {
25      "cents": 0,
26      "currency": "USD"
27    },
28    "total": {
29      "cents": 546,
30      "currency": "USD"
31    },
32    "subscription": {
33      "_id": "680fe4d832ddccc1ee91885e",
34      "customer": "66ce47a1e487adc8f4ab0d46",
35      "merchant": "66311727a26b3cb28faaf97d",
36      "plan": {
37        "amount": {
38          "cents": 500,
39          "currency": "USD"
40        },
41        "_id": "67bf86d03716ba82ce5cd096",
42        "merchant": "66311727a26b3cb28faaf97d",
43        "name": "creator1234",
44        "code": "music_access",
45        "interval": "Monthly",
46        "duration": 12,
47        "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
48        "active": true,
49        "__v": 0
50      },
51      "cardProcessor": "mock",
52      "reference": "f008bb21-f6a1-4947-b271-90e78638f379",
53      "nextPaymentAt": "2025-05-28T20:28:08.164Z",
54      "status": "Active",
55      "webhookInfo": {
56        "item": "sword"
57      },
58      "createdAt": "2025-04-28T20:28:08.169Z",
59      "updatedAt": "2025-04-28T20:28:08.169Z",
60      "__v": 0
61    },
62    "merchantId": "testtest",
63    "customerId": "78C3dn4yUJST9pcX9GtA3yWBcKUCjDw1RWqw1MLpoUDh",
64    "rawCustomerId": "78C3dn4yUJST9pcX9GtA3yWBcKUCjDw1RWqw1MLpoUDh"
65  }
66}
Card Payment Authorized
1// Sent when a subscription renewal card is authorized but not yet captured
2{
3  "eventType": "Card Payment Authorized",
4  "category": "Purchase",
5  "created": "2025-04-28T20:31:19.543Z",
6  "data": {
7    "webhookInfo": {
8      "item": "sword"
9    },
10    "subtotal": {
11      "cents": 500,
12      "currency": "USD"
13    },
14    "fees": {
15      "cents": 46,
16      "currency": "USD"
17    },
18    "gasFees": {
19      "cents": 0,
20      "currency": "USD"
21    },
22    "chargebackProtectionFees": {
23      "cents": 0,
24      "currency": "USD"
25    },
26    "total": {
27      "cents": 546,
28      "currency": "USD"
29    },
30    "merchantId": "testtest",
31    "id": "39ffc711-8023-46cf-b6ad-5dac81afec88",
32    "subscription": {
33      "_id": "67d07938a899c293e0ae2147",
34      "customer": "67d07935a899c293e0ae2132",
35      "merchant": "66311727a26b3cb28faaf97d",
36      "plan": {
37        "amount": {
38          "cents": 500,
39          "currency": "USD"
40        },
41        "_id": "67bf86d03716ba82ce5cd096",
42        "merchant": "66311727a26b3cb28faaf97d",
43        "name": "creator1234",
44        "code": "music_access",
45        "interval": "Monthly",
46        "duration": 12,
47        "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
48        "active": true,
49        "__v": 0
50      },
51      "cardProcessor": "mock",
52      "reference": "148a2d77-c025-4c48-bccb-f8474ffcf903",
53      "nextPaymentAt": "2025-05-11T17:56:08.261Z",
54      "status": "Active",
55      "webhookInfo": {
56        "item": "sword"
57      },
58      "createdAt": "2025-03-11T17:56:08.262Z",
59      "updatedAt": "2025-04-11T20:30:00.146Z",
60      "__v": 0
61    },
62    "customerId": "67Lj6ZcTRDtWT3Rx4KWAdLUrHKeLcycBzwvhzGowrHjx",
63    "rawCustomerId": "67Lj6ZcTRDtWT3Rx4KWAdLUrHKeLcycBzwvhzGowrHjx"
64  }
65}
Card Payment Declined
1// Sent when a subscription renewal card is declined by the issuing bank
2{
3  "eventType": "Card Payment Declined",
4  "category": "Purchase",
5  "created": "2025-04-28T20:21:50.163Z",
6  "data": {
7    "webhookInfo": {
8      "item": "sword"
9    },
10    "subtotal": {
11      "cents": 500,
12      "currency": "USD"
13    },
14    "fees": {
15      "cents": 46,
16      "currency": "USD"
17    },
18    "gasFees": {
19      "cents": 0,
20      "currency": "USD"
21    },
22    "chargebackProtectionFees": {
23      "cents": 0,
24      "currency": "USD"
25    },
26    "total": {
27      "cents": 546,
28      "currency": "USD"
29    },
30    "merchantId": "testtest",
31    "id": "bce7ca59-4bcc-43c3-95f1-51f2858b0bd2",
32    "declineCode": "59",
33    "declineDescription": "The transaction is suspected of fraud.",
34    "customerId": "67Lj6ZcTRDtWT3Rx4KWAdLUrHKeLcycBzwvhzGowrHjx",
35    "rawCustomerId": "67Lj6ZcTRDtWT3Rx4KWAdLUrHKeLcycBzwvhzGowrHjx"
36  }
37}

Schema

Subscription Lifecycle Event Schema

Applies to: Subscription Created, Subscription Canceled, Subscription Expired, Subscription Failure

Schema
1{
2  "eventType": "string",
3  "category": "Subscription",
4  "created": "string (ISO 8601)",
5  "data": {
6    "planCode": "string",
7    "planName": "string",
8    "subscriptionId": "string",
9    "customerId": "string",
10    "amount": { "cents": "number", "currency": "string" },
11    "interval": "string (Monthly | Yearly | Weekly | Daily)",
12    "fundingMethod": "string (Card)",
13    "webhookInfo": { "key": "value" },
14    "reason": "string (optional — present on Canceled and Expired events)"
15  }
16}

Subscription Payment Event Schema

Applies to: Settled, Card Payment Authorized, Card Payment Declined (when triggered by a subscription billing cycle)

Schema
1{
2  "eventType": "string",
3  "category": "Purchase",
4  "created": "string (ISO 8601)",
5  "data": {
6    "id": "string",
7    "signature": "string (present on Settled)",
8    "webhookInfo": { "key": "value" },
9    "subtotal": { "cents": "number", "currency": "string" },
10    "fees": { "cents": "number", "currency": "string" },
11    "gasFees": { "cents": "number", "currency": "string" },
12    "chargebackProtectionFees": { "cents": "number", "currency": "string" },
13    "total": { "cents": "number", "currency": "string" },
14    "merchantId": "string",
15    "customerId": "string",
16    "rawCustomerId": "string",
17    "declineCode": "string (present on Card Payment Declined)",
18    "declineDescription": "string (present on Card Payment Declined)",
19    "subscription": {
20      "_id": "string",
21      "status": "string (Active | Canceled | Expired)",
22      "nextPaymentAt": "string (ISO 8601)",
23      "plan": {
24        "code": "string",
25        "name": "string",
26        "interval": "string",
27        "duration": "number",
28        "amount": { "cents": "number", "currency": "string" }
29      },
30      "webhookInfo": { "key": "value" }
31    }
32  }
33}