Billing Meters
Billing Meters are unique customer actions that can be tracked and billed within your app. The Billing Meter API allows you to create, retrieve, update, and delete billing meters.
The Billing Meter Object
Attributes
Unique identifier for the billing meter.
The name of the billing event or trigger, e.g., "frame_gives_you_billing".
A human-readable label for this billing meter, e.g., "Kyc Initiated".
A brief description of what this billing meter tracks or represents.
The amount associated with this billing event, in string format.
Defines how multiple occurrences are combined.
A percentage markup applied for calculations.
Current status of the billing meter.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
String representing the object's type. Always "billing_meter".
Time at which the billing meter was created.
Time at which the billing meter was last updated.
{
"id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
"status": "active",
"livemode": false,
"aggregation": "sum",
"event_name": "frame_gives_you_billing",
"description": "Begin Kyc flow with User",
"display_name": "Kyc Initiated",
"value": "5.0",
"object": "billing_meter",
"created": 1760024670,
"updated": 1760024670
}
List All Billing Meters
Retrieves a list of billing meters for your account, with optional filtering by status and customer.
Parameters
A limit on the number of objects to be returned. Range: 1 to 100, default is 10.
The page offset for fetching data.
Filter meters by status.
Filter meters by customer ID.
Returns
A dictionary with a data property that contains an array of billing meter objects. If no more meters are available, the resulting array will be empty.
curl --request GET \
--url https://api.framepayments.com/v1/billing/meters \
--header 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
"status": "active",
"livemode": false,
"aggregation": "sum",
"event_name": "frame_gives_you_billing",
"description": "Begin Kyc flow with User",
"display_name": "Kyc Initiated",
"value": "5.0",
"object": "billing_meter",
"created": 1760024670,
"updated": 1760024670
}
],
"meta": {
"page": 1,
"url": "/v1/billing/meters",
"has_more": false,
"prev": null,
"next": null
}
}
Create a Billing Meter
Creates a new billing meter that can be used to track and bill for specific events or actions.
Parameters
The name of the billing event or trigger. Must be unique across your account.
A human-readable label for this billing meter. This will be 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.
Defines how multiple occurrences are combined.
A percentage markup applied for calculations. For example, 2.5 for a 2.5% markup.
curl --request POST \
--url https://api.framepayments.com/v1/billing/meters \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
"event_name": "api_call",
"display_name": "API Call",
"description": "Each API call to our service",
"value": 1.0,
"aggregation": "count",
"markup_percentage": 5.0
}'
{
"id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
"status": "active",
"livemode": false,
"aggregation": "count",
"event_name": "api_call",
"description": "Each API call to our service",
"display_name": "API Call",
"value": "1.0",
"markup_percentage": 5.0,
"object": "billing_meter",
"created": 1760024670,
"updated": 1760024670
}
Update a Billing Meter
Updates an existing billing meter's properties.
Parameters
The ID of the billing meter to update.
The new name of the billing event or trigger. Must be unique across your account.
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.
Defines how multiple occurrences are combined. Note: Changing this may affect how existing events are aggregated.
The status of the billing meter. Can be active, inactive, or pending.
curl --request PATCH \
--url https://api.framepayments.com/v1/billing/meters/41411633-b804-4cf0-bb75-a9fc2c35b36e \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
"display_name": "Updated API Call",
"description": "Updated description for API calls",
"value": 1.5
}'
{
"id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
"status": "active",
"livemode": false,
"aggregation": "count",
"event_name": "api_call",
"description": "Updated description for API calls",
"display_name": "Updated API Call",
"value": "1.5",
"markup_percentage": 5.0,
"object": "billing_meter",
"created": 1760024670,
"updated": 1760025670
}
Retrieve a Billing Meter
Retrieves the details of an existing billing meter.
Parameters
The ID of the billing meter to retrieve.
Returns
Returns the billing meter object if a valid ID was provided. Returns an error if the billing meter doesn't exist or if you don't have permission to access it.
curl --request GET \
--url https://api.framepayments.com/v1/billing/meters/41411633-b804-4cf0-bb75-a9fc2c35b36e \
--header 'Authorization: Bearer YOUR_API_KEY'
{
"id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
"status": "active",
"livemode": false,
"aggregation": "count",
"event_name": "api_call",
"description": "Updated description for API calls",
"display_name": "Updated API Call",
"value": "1.5",
"markup_percentage": 5.0,
"object": "billing_meter",
"created": 1760024670,
"updated": 1760025670
}
Delete a Billing Meter
Permanently deletes a billing meter. This action cannot be undone.
Parameters
The ID of the billing meter to delete.
Returns
Returns an object with the ID of the deleted billing meter and a deleted flag set to true.
Note: Once deleted, you can no longer record events for this meter or include it in billing calculations.
curl --request DELETE \
--url https://api.framepayments.com/v1/billing/meters/41411633-b804-4cf0-bb75-a9fc2c35b36e \
--header 'Authorization: Bearer YOUR_API_KEY'
{
"id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
"deleted": true
}