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.

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
  }
}

Event Fields

Field	Type	Description
id	string	Unique identifier for the webhook event.
type	string	The event type: `billing.subscriber_overage`.
object	string	Object type, always `event`.
created	integer	Unix timestamp of when the event was created.
livemode	boolean	Indicates whether this is a live (`true`) or test (`false`) event.

Data Object Fields

Field	Type	Description
id	string	Unique identifier for the billing report.
object	string	Object type: `billing_report`.
start_date	integer	Unix timestamp of the billing period start date.
end_date	integer	Unix timestamp of the billing period end date.
customer	string	The unique identifier of the customer.
subscription	string	The unique identifier of the subscription.
invoice	string	The unique identifier of the associated invoice.
usage	integer	The total usage recorded for the billing period.
amount_cents	integer	The overage amount charged in cents.
created	integer	Unix timestamp of when the report was generated.

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.

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
  }
}

Event Fields

Field	Type	Description
id	string	Unique identifier for the webhook event.
type	string	The event type: `billing.subscriber_usage`.
object	string	Object type, always `event`.
created	integer	Unix timestamp of when the event was created.
livemode	boolean	Indicates whether this is a live (`true`) or test (`false`) event.

Data Object Fields

Field	Type	Description
id	string	Unique identifier for the billing report.
object	string	Object type: `billing_report`.
start_date	integer	Unix timestamp of the billing period start date.
end_date	integer	Unix timestamp of the billing period end date.
customer	string	The unique identifier of the customer.
subscription	string	The unique identifier of the subscription.
invoice	string	The unique identifier of the associated invoice.
usage	integer	The current usage recorded for the billing period.
amount_cents	integer	The current amount in cents based on usage.
created	integer	Unix timestamp of when the report was generated.

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.

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
  }
}

Event Fields

Field	Type	Description
id	string	Unique identifier for the webhook event.
type	string	The event type: `billing.credits_usage`.
object	string	Object type, always `event`.
created	integer	Unix timestamp of when the event was created.
livemode	boolean	Indicates whether this is a live (`true`) or test (`false`) event.

Data Object Fields

| Field | Type | Description | | ----------------- | --------------- | ---------------------------------------------------------------------- | --- | | id | string | Unique identifier for the billing credits record. | | object | string | Object type: billing_credits. | | | customer_id | string | The unique identifier of the customer. | | billing_credits | float | The total number of credits allocated. | | available_credits | float | The number of credits remaining. | | used_credits | float | The number of credits consumed. | | status | string | The status of the credits: active, expired, depleted. | | expired_at | integer | null | Unix timestamp of when the credits expired, or null if still active. | | expires_at | integer | Unix timestamp of when the credits will expire. | | created_at | integer | Unix timestamp of when the credits were allocated. |

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.

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
  }
}

Event Fields

Field	Type	Description
id	string	Unique identifier for the webhook event.
type	string	The event type: `billing.credits_expired`.
object	string	Object type, always `event`.
created	integer	Unix timestamp of when the event was created.
livemode	boolean	Indicates whether this is a live (`true`) or test (`false`) event.

Data Object Fields

Field	Type	Description
id	string	Unique identifier for the billing credits record.
object	string	Object type: `billing_credits`.
customer_id	string	The unique identifier of the customer.
billing_credits	float	The total number of credits that were allocated.
available_credits	float	The number of credits that were remaining at expiration.
used_credits	float	The number of credits that were consumed before expiration.
status	string	The status of the credits: `expired`.
expired_at	integer	Unix timestamp of when the credits expired.
expires_at	integer	Unix timestamp of the scheduled expiration date.
created_at	integer	Unix timestamp of when the credits were allocated.

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.