Billing
Usage-based billing. Define billing metrics (meters) to track usage events, then generate invoices and reports against accumulated usage.
The Billing object
Attributes
Customer ID this credit is issued to
Account ID this credit is issued to
Product ID this credit is linked to
Total credits allocated
Credits remaining
Credits consumed
Credit status (e.g. active)
Whether this credit is flagged for monitoring
Unix timestamp when credits expire
Unix timestamp
Unix timestamp
{
"id": null,
"object": "billing_credit",
"customer": null,
"account": null,
"product": null,
"billing_credits": null,
"available_credits": null,
"used_credits": null,
"status": null,
"watchlist": false,
"expires": null,
"livemode": false,
"created": 0,
"updated": 0
}
Issue a billing credit
Issues billing credits to a customer that can be used to offset future billing charges. Billing credits enable you to allocate credits to customers that can be applied against future billing charges. Credits can be linked to specific products, have expiration dates, and track usage over time. When credits are exhausted, Frame fires the billing_credit.exhausted webhook event.
Query parameters
The unique identifier (UUID) of the customer to issue credits to. Mutually exclusive with account.
Account ID to issue credits to. Mutually exclusive with customer.
The unique identifier (UUID) of the product or billing plan this credit is linked to.
The number of billing credits to allocate to the customer.
The date when the billing credits expire and can no longer be used, in ISO 8601 format.
Whether the credit pool is capped at the allocated amount.
Returns
Returns the created billing credit object if successful.
curl --request POST \
--url https://api.framepayments.com/v1/billing/billing_credit \
--header 'Authorization: Bearer API_KEY'
{
"id": "d644dc4c-2e27-41e9-9d89-4d63b6b5a56b",
"billing_credits": "98.06",
"available_credits": "98.06",
"used_credits": "0.0",
"status": "active",
"watchlist": false,
"product": "4819b076-80dd-4daa-964a-f446976d207d",
"customer": "76c36e08-7820-450d-98ee-41971985e475",
"account": null,
"account_id": null,
"object": "billing_credit",
"created": 1781115863,
"updated": 1781115863,
"livemode": false,
"expires": 1780675052
}
Retrieve billing credit usage
Retrieves the billing credits for a specific customer, including available and consumed credit balances. Returns the billing credit object if found, or an error if the customer has no billing credits.
Path parameters
Billing credit ID
Returns
Returns the billing credit object with available and consumed credit balances.
curl --request GET \
--url https://api.framepayments.com/v1/billing/billing_credit/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "9a5a2b86-c0ef-46ef-ad5a-8755c8877b23",
"billing_credits": "46.57",
"available_credits": "46.57",
"used_credits": "0.0",
"status": "active",
"watchlist": false,
"product": "d0819bde-a141-4593-bcf2-c1563678947b",
"customer": "110a6b76-597f-4b6d-8025-f93a5222e786",
"account": null,
"account_id": null,
"object": "billing_credit",
"created": 1781115863,
"updated": 1781115863,
"livemode": false,
"expires": 1780537374
}
Generate invoice from billing report
Generates an invoice from a billing report period. Use this to convert accumulated billing metric usage into a chargeable invoice for postpaid billing or when credits are exhausted. Line items are automatically populated from the usage events in the specified date range.
Query parameters
Customer ID to generate the invoice for. Mutually exclusive with account.
Account ID to generate the invoice for. Mutually exclusive with customer.
Start date of the billing period in ISO 8601 format.
End date of the billing period in ISO 8601 format.
How payment is collected. request_payment sends the invoice to the customer for manual payment; charge_automatically immediately charges their default payment method.
A description for the invoice.
A memo or note to include on the invoice.
Payment terms in days.
Comma-separated billing metric event names to include in the invoice.
Returns
Returns the generated invoice object with line items populated from the usage events in the specified date range.
curl --request POST \
--url https://api.framepayments.com/v1/billing/billing_invoice \
--header 'Authorization: Bearer API_KEY'
{
"id": "c198fa45-289c-4e11-9001-4119031d6124",
"invoice_number": "1",
"collection_method": "request_payment",
"status": "draft",
"due_date": null,
"description": "Invoice description",
"memo": null,
"net_terms": 0,
"object": "invoice",
"total": 1000,
"currency": "USD",
"livemode": false,
"created": 1781115864,
"updated": 1781115864,
"metadata": {},
"customer": {
"id": "857caee9-ae8a-4307-8753-ee4c07575326",
"name": "Marion Hickle",
"email": "customer@frame.com",
"description": "in",
"status": "active",
"date_of_birth": null,
"phone": "+13107484186",
"payment_methods": [],
"billing_address": null,
"shipping_address": null,
"object": "customer",
"created": 1781115863,
"updated": 1781115863,
"livemode": false,
"metadata": {}
},
"line_items": []
}
Get usage report for a customer
Generates a billing report for a specific customer within a given time range. Billing reports aggregate customer usage data across billing metrics, providing a detailed breakdown of consumption during a billing period. Provide either customer or account — not both.
Query parameters
The ID of the customer to get the report for. Mutually exclusive with account.
Account ID to get the report for. Mutually exclusive with customer.
Start date for the report period in ISO 8601 format.
End date for the report period in ISO 8601 format.
Returns
Returns a billing report object with aggregated usage for the customer.
curl --request GET \
--url https://api.framepayments.com/v1/billing/report/customer \
--header 'Authorization: Bearer API_KEY'
{
"aggregated_usage": [],
"customer": null,
"account": null,
"account_id": null,
"usage": "0.0",
"livemode": false
}
Get usage report for a specific billing metric
Generates a report for a specific billing event within a given time range. Returns a billing report object for the specified event.
Path parameters
The name of the billing event to generate the report for.
Query parameters
The ID of the customer to filter the report by.
Start date for the report period in ISO 8601 format.
End date for the report period in ISO 8601 format.
Returns
Returns a billing report object for the specified event.
curl --request GET \
--url https://api.framepayments.com/v1/billing/report/event/<event_name> \
--header 'Authorization: Bearer API_KEY'
{
"object": "billing_report",
"aggregation": "sum",
"event_name": "61ba1cd3-faf4-48ee-bbb5-b3494d0815a9",
"usage": "0.0",
"billing_metric": "a9afd5fc-ecc6-47e1-b22c-0d47bc6b4564",
"customer": null,
"account": null,
"account_id": null,
"livemode": false
}
Get usage report for multiple billing metrics
Generates reports for multiple billing events within a given time range. Returns aggregated usage for multiple billing metric event types in a single call. Pass event names as a comma-separated query parameter.
Query parameters
Comma-separated list of event names to include in the report (e.g. api_call,storage_gb).
The ID of the customer to get the report for.
Start date for the report period in ISO 8601 format.
End date for the report period in ISO 8601 format.
Returns
Returns a billing report object with aggregated usage for the specified events.
curl --request GET \
--url https://api.framepayments.com/v1/billing/report/events \
--header 'Authorization: Bearer API_KEY'
{
"aggregated_usage": [],
"customer": null,
"account": null,
"account_id": null,
"usage": "0.0",
"livemode": false
}
Get usage report for a subscription
Returns the billing report for a specific subscription in the current subscription period. Provides aggregated billing metric usage for the subscription.
Query parameters
The ID of the subscription to get the report for.
Returns
Returns a billing report object with aggregated usage for the subscription.
curl --request GET \
--url https://api.framepayments.com/v1/billing/report/subscription \
--header 'Authorization: Bearer API_KEY'
{
"aggregated_usage": [],
"customer": null,
"account": null,
"account_id": null,
"usage": "0.0",
"livemode": false
}
Get threshold progress for a customer or account
Returns how close a customer or account is to hitting a billing threshold. Billing events accumulate as pending charges and this endpoint tracks progress toward the auto-charge threshold. Provide either customer or account — not both.
Query parameters
Customer ID (mutually exclusive with account)
Account ID (mutually exclusive with customer)
Returns
Returns a threshold progress object showing accumulated charges, the threshold target, and progress percentage.
curl --request GET \
--url https://api.framepayments.com/v1/billing/report/threshold_progress \
--header 'Authorization: Bearer API_KEY'
{
"object": "threshold_progress",
"accumulated_amount_cents": 5000,
"threshold_amount_cents": 10000,
"threshold_percentage": 50,
"oldest_pending_charge_at": null,
"period_start": "2026-05-11T18:24:24Z",
"period_end": "2026-06-10T18:24:24Z",
"billing_cycle": "monthly",
"customer": null,
"account": null,
"account_id": null,
"livemode": false
}
Record a billing metric event
Creates a new billing metric event to track customer usage. Billing metric events are discrete instances of a customer's usage for a given billing metric. Include a reference field as an idempotency key to prevent duplicate charges — submitting a duplicate reference for the same event_name is silently ignored, making it safe to retry.
Query parameters
The name of the billing meter this event is associated with.
A unique reference for this event. Acts as an idempotency key — duplicate references for the same event_name are silently ignored.
The ID of the customer this event is associated with.
The measured value for this event (e.g. 1.0 for a single API call, 2.5 for GB of storage).
The time when this event occurred in ISO 8601 format. Defaults to current time if not provided.
A percentage markup applied for calculations.
Returns
Returns the created billing metric event object.
curl --request POST \
--url https://api.framepayments.com/v1/billing/metering_events \
--header 'Authorization: Bearer API_KEY'
{
"id": "4c4efc6f-c857-4f4f-8fae-c5fca8f602ee",
"reference": "evt_9d4c7fe9c2580071",
"value": "1.0",
"timestamp": "2026-06-10T18:24:25.000Z",
"customer": "d450f6ac-3fc9-4adf-b35b-9d68d111e00a",
"billing_metric": "8f9cb601-eef1-42ea-8c7c-1865fbec8a72",
"object": "billing_metric_event",
"created": 1781115865,
"updated": 1781115865,
"livemode": false
}
Retrieve a billing metric event
Retrieves the details of an existing billing metric event using the event's ID or reference key. Returns the billing metric event object if found, or an error if the event doesn't exist.
Path parameters
The ID or reference key of the billing metric event to retrieve.
Returns
Returns the billing metric event object.
curl --request GET \
--url https://api.framepayments.com/v1/billing/metering_events/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "5455091d-51f6-4cb3-8b0a-9144e2d6284c",
"reference": "qwlpcsgkjh",
"value": "8458.35",
"timestamp": "2026-06-10T05:47:27.000Z",
"customer": "71643e27-796f-41c7-9904-d8cf029b11ea",
"billing_metric": "02a8ee76-0673-4123-8d6c-53a094ad20fb",
"object": "billing_metric_event",
"created": 1781115865,
"updated": 1781115865,
"livemode": false
}
Update a billing metric event
Updates the specified billing metric event by setting the values of the parameters passed. Returns the updated billing metric event object if successful, or an error if the event doesn't exist or the update fails.
Path parameters
The ID or reference key of the billing metric event to update.
Query parameters
The new measured value for this event.
The reference key to identify the event.
Returns
Returns the updated billing metric event object.
curl --request PATCH \
--url https://api.framepayments.com/v1/billing/metering_events/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "dfc5eef7-095c-4373-98b6-47949926bee6",
"reference": "tacgoqcmoi",
"value": "5.0",
"timestamp": "2026-06-01T08:13:47.000Z",
"customer": "e599959f-4930-4c7d-b12f-623ad751806c",
"billing_metric": "b42d0dc6-d9f3-4adb-becf-1bad3046ea5f",
"object": "billing_metric_event",
"created": 1781115865,
"updated": 1781115865,
"livemode": false
}
Create a billing metric
Creates a new billing meter that can be used to track and bill for specific events or actions. Billing meters are unique customer actions that can be tracked and billed within your app. Each meter has a unique event_name that metering events reference when recording usage.
Query parameters
The name of the billing event or trigger. Must be unique across your account.
Defines how multiple occurrences are combined. One of sum, average, count, or count_unique. Use count_unique to deduplicate by idempotency key.
A human-readable label for this billing meter, displayed in the dashboard.
A brief description of what this billing meter tracks.
The amount associated with this billing event. For count-based meters, this is typically 1.0.
A percentage markup applied for calculations. For example, 2.5 for a 2.5% markup.
Returns
Returns the newly created billing meter object.
curl --request POST \
--url https://api.framepayments.com/v1/billing/metering \
--header 'Authorization: Bearer API_KEY'
{
"id": "115a69dc-9d28-4fdd-a900-6a25f4170c58",
"status": "active",
"aggregation": "count",
"event_name": "api_call",
"description": "Counts each API call made by the customer",
"display_name": "API Calls",
"value": "0.0",
"object": "billing_metric",
"created": 1781115865,
"updated": 1781115865,
"livemode": false
}
Retrieve a billing metric
Retrieves the details of an existing billing meter. Returns the billing meter object if a valid ID was provided, or an error if the billing meter doesn't exist.
Path parameters
Billing metric ID
Returns
Returns the billing meter object.
curl --request GET \
--url https://api.framepayments.com/v1/billing/metering/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "955ad413-9ce3-49b5-b3c9-6f19cea98d97",
"status": "active",
"aggregation": "count",
"event_name": "9ff0a6df-7196-4e8f-b467-c8147813f1dd",
"description": "Description of the sample event",
"display_name": "Sample Event",
"value": "36.13",
"object": "billing_metric",
"created": 1781115865,
"updated": 1781115865,
"livemode": false
}
Update a billing metric
Updates an existing billing meter's properties. Note: Changing the aggregation may affect how existing events are aggregated.
Path parameters
The ID of the billing meter to update.
Query parameters
A new human-readable label for this billing meter.
A new description of what this billing meter tracks.
The new amount associated with this billing event.
A percentage markup applied for calculations.
Pass false to deactivate the billing meter.
Returns
Returns the updated billing meter object.
curl --request PATCH \
--url https://api.framepayments.com/v1/billing/metering/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "94b90e56-d1e7-4429-8586-1722175402bc",
"status": "active",
"aggregation": "count",
"event_name": "33a66f9b-de2c-43ff-a923-4115ad058e39",
"description": "Description of the sample event",
"display_name": "Updated Display Name",
"value": "57.67",
"object": "billing_metric",
"created": 1781115865,
"updated": 1781115865,
"livemode": false
}