Billing

Subscribe to webhook events for subscription and billing status changes.

This section describes Billing webhooks, which are only applicable for API version 2025-06-16 and later.

The following webhook events are available for your Billing integration.

Event	Description
subscription.created	A subscription has been created.
subscription.in_trial	The subscription transits to IN_TRIAL status.
subscription.active	The subscription transits to ACTIVE status.
subscription.unpaid	The subscription transits to UNPAID status.
subscription.modified	The subscription is updated.
subscription.cancelled	The subscription has been cancelled.
invoice.created	The invoice has been created.
invoice.finalized	The invoice has been finalized.
invoice.voided	The invoice has been voided.
invoice.updated	The invoice has been updated.
invoice.payment.paid	The invoice has been paid.
billing_transaction.created	The Billing Transaction has been created.
billing_transaction.succeeded	The Billing Transaction has succeeded.
billing_transaction.cancelled	The Billing Transaction has been cancelled.
billing_checkout.created	The Billing Checkout has been created.
billing_checkout.cancelled	The Billing Checkout has been cancelled.
billing_checkout.completed	The Billing Checkout has completed.
usage_event.aggregation_failed	The Failed Billing Usage Events have been aggregated at 10-minute.
credit_note.created	The credit note has been created.
credit_note.finalized	The credit note has been finalized.
credit_note.voided	The credit note has been voided.

This section describes the Billing webhook, which are only applicable for API version 2025-04-25 and before.

Event	Description
subscription.created	A subscription has been created.
subscription.updated	The subscription has been changed, such as status update, trial start and end, cancel at period end, and so on.
subscription.cancelled	The subscription has been cancelled.
invoice.sent	The invoice is ready to be paid.
invoice.paid	The invoice has been paid successfully.
invoice.payment_failed	The invoice is marked as PAYMENT_FAILED and should be treated as bad debt in the accounting process.
invoice.payment_attempt_failed	A payment attempt on the invoice failed.

Payload examples

subscription.*

JSON

1{
2    "id": "790fb1e1-01e6-41d5-a821-297d51b43599",
3    "name": "subscription.created",
4    "account_id": "acct__ncI2nypPKSq2VXKxscAcg",
5    "created_at": "2022-08-02T03:07:55+0000",
6    "data":Object{...}
7}

data is the response body from Retrieve a Subscription API of the corresponding API version you subscribe to.

invoice.*

JSON

1{
2    "id":"9c830876-5290-4a46-b3b0-aa3c6d8e8b50",
3    "name":"invoice.created",
4    "account_id":"acct__ncI2nypPKSq2VXKxscAcg",
5    "created_at": "2022-08-02T03:07:55+0000",
6    "data":Object{...}
7}

data is the response body from Retrieve an Invoice API of the corresponding API version you subscribe to.

billing_transaction.*

JSON

1{
2    "id":"9c830876-5290-4a46-b3b0-aa3c6d8e8b50",
3    "name":"billing_transaction.created",
4    "account_id":"78814faa-1b30-4598-a9c8-f0583db8d09d",
5    "created_at": "2022-08-02T03:07:55+0000",
6    "data":Object{...}
7}

data is the response body from Retrieve a Billing Transaction API of the corresponding API version you subscribe to.

billing_checkout.*

JSON

1{
2    "id":"2a396f97-92f4-3075-98fa-43acf6e87412",
3    "name":"billing_checkout.created",
4    "account_id":"78814faa-1b30-4598-a9c8-f0583db8d09d",
5    "created_at": "2025-07-30T07:39:43+0000",
6    "data":Object{...}
7}

data is the response body from Retrieve a Billing Checkout API of the corresponding API version you subscribe to.

usage_event.aggregation_failed

JSON

1{
2    "id": "2a396f97-92f4-3075-98fa-43acf6e87412",
3    "name": "usage_event.aggregation_failed",
4    "org_id": "acct_t6nlGSCgPpWIBE-3ncOTxA",
5    "created_at": "2025-09-16T07:20:19+0000",
6    "version": "2025-06-21",
7    "data": Object{...}
8}

data describes a summary of failure events during this period:

from_ingested_at: the start timestamp of the time range when events were ingested into the system.
to_ingested_at: the end timestamp of the time range when events were ingested into the system.
total_failed_event_count: the total number of events that failed to be processed during the specified time range.
error_samples: an array containing sample error cases from the failed events. Provides representative examples of the types of errors that occurred, rather than listing all failed events. Each object in the array follows the following schema:
- error: details about the error of the event ingestion. Object schema follows API Errors API.
- merchant_event_id: a unique identifier for the event sample, provided by the user.

JSON

1{
2    "from_ingested_at": "2025-08-01T01:00:00+0000",
3    "to_ingested_at": "2025-08-01T01:10:00+0000",
4    "total_failed_event_count": 20000,
5    "error_samples": [
6        {
7        "error": {
8            "code": "validation_error",
9            "source": "merchant_event_id",
10            "message": "The 'merchant_event_id' is duplicated within 35 days."
11        },
12        "merchant_event_id": "completion-a4b1c2d3-e4f5-g6h7-i8j9-k0l1m2n3o4p5"
13        },
14        {
15        "error": {
16            "code": "validation_error",
17            "source": "properties",
18            "message": "missing property 'total_tokens' for meter 'mtr_hkpdwesy9gazzrt'"
19        },
20        "merchant_event_id": "completion-a4b1c2d3-e4f5-g6h7-i8j9-k0l1m2n3o4p6"
21        },
22        {
23        "error": {
24            "code": "validation_error",
25            "source": "properties",
26            "message": "property 'total_tokens' value is not a number for meter 'mtr_hkpdwesy9gazzrtqbkg'"
27        },
28        "merchant_event_id": "completion-a4b1c2d3-e4f5-g6h7-i8j9-k0l1m2n3o4p7"
29        },
30        {
31        "error": {
32            "code": "resource_not_found",
33            "source": "billing_customer_id",
34            "message": "The Customer with ID bcus_sgpdtcpm4hdm407yepr cannot be found."
35        },
36        "merchant_event_id": "completion-a4b1c2d3-e4f5-g6h7-i8j9-k0l1m2n3o4p8"
37        }
38    ]
39}

credit_note.*

JSON

1{
2    "id": "9c830876-5290-4a46-b3b0-aa3c6d8e8b50",
3    "name": "credit_note.created",
4    "account_id": "acct__ncI2nypPKSq2VXKxscAcg",
5    "created_at": "2025-01-02T03:07:55+0000",
6    "data":Object{...}
7}

data is the response body from Retrieve a Credit Note API of the corresponding API version you subscribe to.

This section describes the Billing webhook, which are only applicable for API version 2025-04-25 and before.

subscription.*

JSON

1{
2    "id": "790fb1e1-01e6-41d5-a821-297d51b43599",
3    "name": "subscription.created",
4    "source_id": "sub_hkstzqcl4gc7ma2ykn7",
5    "account_id": "78814faa-1b30-4598-a9c8-f0583db8d09d",
6    "created_at": "2022-08-02T03:07:55+0000",
7    "data":{
8        "object": {...}
9    }
10}

object is the response body from Retrieve a Subscription API

JSON

1{
2  "id": "sub_hkstzqcl4gc7ma2ykn7",
3  "status": "ACTIVE",
4  "customer_id": "cus_hkst2q96fgbzw4gdpyc",
5  "payment_consent_id": "cst_hkstp6spzgc7m9xic5y",
6  "latest_invoice_id": "inv_hkstc4dn8gc7ma30pq1",
7  "trial_start_at": null,
8  "trial_end_at": null,
9  "current_period_start_at": "2022-08-02T03:07:53+0000",
10  "current_period_end_at": "2022-09-02T03:07:53+0000",
11  "created_at": "2022-08-02T03:07:55+0000",
12  "updated_at": "2022-08-02T03:07:55+0000",
13  "cancel_at": "2023-08-02T03:07:53+0000",
14  "cancel_at_period_end": false,
15  "cancel_requested_at": null,
16  "next_billing_at": "2022-09-02T03:07:53+0000",
17  "remaining_billing_cycles": 11,
18  "total_billing_cycles": 12,
19  "recurring": {
20    "period": 1,
21    "period_unit": "MONTH"
22  },
23  "metadata": {}
24}

invoice.*

JSON

1{
2    "id":"9c830876-5290-4a46-b3b0-aa3c6d8e8b50",
3    "name":"invoice.sent",
4    "source_id": "inv_hkstc4dn8gc7ma30pq1",
5    "account_id":"78814faa-1b30-4598-a9c8-f0583db8d09d",
6    "created_at": "2022-08-02T03:07:55+0000",
7    "data":{
8        "object": {...}
9    }
10}

object is the response body from Retrieve an Invoice API

JSON

1{
2  "id": "inv_hkstc4dn8gc7ma30pq1",
3  "customer_id": "cus_hkst2q96fgbzw4gdpyc",
4  "status": "SENT",
5  "currency": "USD",
6  "total_amount": 5,
7  "subscription_id": "sub_hkstzqcl4gc7ma2ykn7",
8  "payment_intent_id": "int_hkstp6spzgc7ma34l23",
9  "period_start_at": "2022-08-02T03:07:53+0000",
10  "period_end_at": "2022-09-02T03:07:53+0000",
11  "past_payment_attempt_count": 0,
12  "created_at": "2022-08-02T03:07:53+0000",
13  "updated_at": "2022-08-02T03:07:55+0000"
14}

Was this page helpful?