Billing Webhooks
Frame Payments sends webhook events to notify your application of billing-related activities. These events allow you to automate workflows, monitor customer usage, and take action when thresholds are reached.
Billing Subscriptions Webhooks
billing.subscriber_overage
Triggered when a subscriber has exceeded their subscription quota. Use this event to notify customers of overage charges or to take automated actions such as throttling or upgrading their plan.
Event Fields
Unique identifier for the webhook event.
The event type: billing.subscriber_overage.
Object type, always event.
Unix timestamp of when the event was created.
Indicates whether this is a live (true) or test (false) event.
The event data payload.
{
"id": "787d686b-3f8d-490e-bd90-4a2ab0c5a81f",
"type": "billing.subscriber_overage",
"object": "event",
"created": 1729161970,
"livemode": false,
"data": {
"id": "a8a3b804-c43d-4b71-8eee-faacc198f7f9",
"object": "billing_report",
"start_date": 1729143862,
"end_date": 1729161970,
"customer": "cust_a8a3b804c43d4b718eee",
"subscription": "sub_b9b4c915d54e5c829fff",
"invoice": "inv_c0c5d026e65f6d93a000",
"usage": 1500,
"amount_cents": 5000,
"created": 1729161970
}
}
billing.subscriber_usage
Triggered to inform the merchant of the percentage of a customer's subscription quota that has been used. Use this event to send usage alerts or display usage dashboards to customers.
Event Fields
Unique identifier for the webhook event.
The event type: billing.subscriber_usage.
Object type, always event.
Unix timestamp of when the event was created.
Indicates whether this is a live (true) or test (false) event.
The event data payload.
{
"id": "787d686b-3f8d-490e-bd90-4a2ab0c5a81f",
"type": "billing.subscriber_usage",
"object": "event",
"created": 1729161970,
"livemode": false,
"data": {
"id": "a8a3b804-c43d-4b71-8eee-faacc198f7f9",
"object": "billing_report",
"start_date": 1729143862,
"end_date": 1729161970,
"customer": "cust_a8a3b804c43d4b718eee",
"subscription": "sub_b9b4c915d54e5c829fff",
"invoice": "inv_c0c5d026e65f6d93a000",
"usage": 1500,
"amount_cents": 5000,
"created": 1729161970
}
}
Billing Credit Webhooks
billing.credits_usage
Triggered to inform the merchant of the percentage of a customer's billing credits that have been used. Use this event to alert customers when their credits are running low or to prompt them to purchase additional credits.
Event Fields
Unique identifier for the webhook event.
The event type: billing.credits_usage.
Object type, always event.
Unix timestamp of when the event was created.
Indicates whether this is a live (true) or test (false) event.
The event data payload.
{
"id": "903f808d-5h0f-612g-df12-6c4cd2e7c03h",
"type": "billing.credits_usage",
"object": "event",
"created": 1729180000,
"livemode": false,
"data": {
"id": "c0c5d026-e65f-6d93-a000-hccee310h9h1",
"object": "billing_credits",
"customer_id": "cust_a8a3b804c43d4b718eee",
"billing_credits": 1000.0,
"available_credits": 250.0,
"used_credits": 750.0,
"status": "active",
"expired_at": null,
"expires_at": 1731772000,
"created_at": 1729143862
}
}
billing.credits_expired
Triggered when a customer's billing credits have expired. Use this event to notify customers of the expiration, update internal records, or prompt them to purchase new credits.
Event Fields
Unique identifier for the webhook event.
The event type: billing.credits_expired.
Object type, always event.
Unix timestamp of when the event was created.
Indicates whether this is a live (true) or test (false) event.
The event data payload.
{
"id": "a14g919e-6i1g-723h-eg23-7d5de3f8d14i",
"type": "billing.credits_expired",
"object": "event",
"created": 1731772000,
"livemode": false,
"data": {
"id": "c0c5d026-e65f-6d93-a000-hccee310h9h1",
"object": "billing_credits",
"customer_id": "cust_a8a3b804c43d4b718eee",
"billing_credits": 1000.0,
"available_credits": 250.0,
"used_credits": 750.0,
"status": "expired",
"expired_at": 1731772000,
"expires_at": 1731772000,
"created_at": 1729143862
}
}
Webhook Event Types Summary
| Event Type | Description |
|---|---|
billing.subscriber_overage | Customer has exceeded their subscription quota. |
billing.subscriber_usage | Reports percentage of subscription quota used. |
billing.credits_usage | Reports percentage of billing credits used. |
billing.credits_expired | Customer's billing credits have expired. |