Billing

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

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}

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?