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.

ENDPOINTS

The Billing Meter Object

Attributes
idstring

Unique identifier for the billing meter.

event_namestring

The name of the billing event or trigger, e.g., "frame_gives_you_billing".

display_namestring

A human-readable label for this billing meter, e.g., "Kyc Initiated".

descriptionstring

A brief description of what this billing meter tracks or represents.

valuefloat

The amount associated with this billing event, in string format.

aggregationenum

Defines how multiple occurrences are combined.

sumstring

Sums all values.

averagestring

Averages all values.

countstring

Counts all occurrences.

count_uniquestring

Counts unique occurrences.

markup_percentagefloat

A percentage markup applied for calculations.

statusenum

Current status of the billing meter.

activestring

The billing meter is active.

inactivestring

The billing meter is inactive.

pendingstring

The billing meter is pending activation.

livemodeboolean

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

objectstring

String representing the object's type. Always "billing_meter".

createdtimestamp

Time at which the billing meter was created.

updatedtimestamp

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
per_pageinteger

A limit on the number of objects to be returned. Range: 1 to 100, default is 10.

pageinteger

The page offset for fetching data.

statusenum

Filter meters by status.

activestring

Only return active billing meters.

inactivestring

Only return inactive billing meters.

pendingstring

Only return pending billing meters.

customerstring

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.

GET/v1/billing/meters
curl --request GET \
  --url https://api.framepayments.com/v1/billing/meters \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response
{
  "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
event_nameREQUIREDstring

The name of the billing event or trigger. Must be unique across your account.

display_nameREQUIREDstring

A human-readable label for this billing meter. This will be displayed in the dashboard.

descriptionREQUIREDstring

A brief description of what this billing meter tracks.

valueREQUIREDfloat

The amount associated with this billing event. For count-based meters, this is typically 1.0.

aggregationREQUIREDstring

Defines how multiple occurrences are combined.

  • sum: Sums all values
  • average: Averages all values
  • count: Counts all occurrences
  • count_unique: Counts unique occurrences based on the idempotency_key
markup_percentagefloat

A percentage markup applied for calculations. For example, 2.5 for a 2.5% markup.

POST/v1/billing/meters
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
  }'
Response
{
  "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
idREQUIREDstring

The ID of the billing meter to update.

event_namestring

The new name of the billing event or trigger. Must be unique across your account.

display_namestring

A new human-readable label for this billing meter.

descriptionstring

A new description of what this billing meter tracks.

valuefloat

The new amount associated with this billing event.

aggregationstring

Defines how multiple occurrences are combined. Note: Changing this may affect how existing events are aggregated.

statusstring

The status of the billing meter. Can be active, inactive, or pending.

PATCH/v1/billing/meters/:id
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
  }'
Response
{
  "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
idREQUIREDstring

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.

GET/v1/billing/meters/:id
curl --request GET \
  --url https://api.framepayments.com/v1/billing/meters/41411633-b804-4cf0-bb75-a9fc2c35b36e \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response
{
  "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
idREQUIREDstring

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.

DELETE/v1/billing/meters/:id
curl --request DELETE \
  --url https://api.framepayments.com/v1/billing/meters/41411633-b804-4cf0-bb75-a9fc2c35b36e \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response
{
  "id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "deleted": true
}