Billing Metric Events

Billing Metric Events track specific customer actions that are measured and billed within your application. These events are associated with billing meters and can be used to calculate usage-based charges.

ENDPOINTS

The Billing Metric Event Object

Attributes
idstring

Unique identifier for the billing metric event.

meter_idstring

The ID of the associated billing meter.

customer_idstring

The ID of the customer this event is associated with.

valuefloat

The measured value for this event.

timestampstring

The time when this event occurred in ISO 8601 format.

metadatadictionary

Additional information about the event.

objectstring

The object type, always "billing_metric_event".

livemodeboolean

Indicates if this is in live mode (true) or sandbox/testing (false).

createdinteger

Unix timestamp when the event was created.

updatedinteger

Unix timestamp when the event was last updated.

Billing Metric Event Object
{
  "id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "meter_id": "meter_1234567890",
  "customer_id": "cus_1234567890",
  "value": 5.0,
  "timestamp": "2025-01-01T00:00:00Z",
  "metadata": {},
  "object": "billing_metric_event",
  "livemode": false,
  "created": 1760024670,
  "updated": 1760024670
}

Create a Billing Event

Creates a new billing metric event to track customer usage.

Parameters
event_nameREQUIREDstring

The name of the billing meter this event is associated with.

referenceREQUIREDstring

A unique reference for this event.

customerREQUIREDstring

The ID of the customer this event is associated with.

valueREQUIREDfloat

The measured value for this event.

timestampstring

The time when this event occurred in ISO 8601 format. Defaults to current time if not provided.

metadatadictionary

Additional information about the event.

Returns

Returns the created billing metric event object if successful. Returns an error if the request is invalid.

POST/v1/billing/metering_events
curl -X POST "https://api.framepayments.com/v1/billing/metering_events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "value": 2,
    "timestamp": "2025-08-29T09:09:09.062103Z",
    "reference": "reference-9",
    "event_name": "kyc_attempt",
    "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9"
  }'
Response
{
  "id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "meter_id": "meter_1234567890",
  "customer_id": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "value": 2.0,
  "timestamp": "2025-08-29T09:09:09.062103Z",
  "metadata": {},
  "object": "billing_metric_event",
  "livemode": false,
  "created": 1735468149,
  "updated": 1735468149
}

Retrieve a Billing Event

Retrieves the details of an existing billing metric event using the event's ID.

Parameters
idREQUIREDstring

The ID of the billing metric event to retrieve.

Returns

Returns the billing metric event object if found, or an error if the event doesn't exist.

GET/v1/billing/metering_events/:id
curl "https://api.framepayments.com/v1/billing/metering_events/41411633-b804-4cf0-bb75-a9fc2c35b36e" \
  -H "Authorization: Bearer API_KEY"
Response
{
  "id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "meter_id": "meter_1234567890",
  "customer_id": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "value": 2.0,
  "timestamp": "2025-08-29T09:09:09.062103Z",
  "metadata": {},
  "object": "billing_metric_event",
  "livemode": false,
  "created": 1735468149,
  "updated": 1735468149
}

Update a Billing Event

Updates the specified billing metric event by setting the values of the parameters passed.

Parameters
idREQUIREDstring

The ID of the billing metric event to update.

valuefloat

The new measured value for this event.

timestampstring

The updated time when this event occurred in ISO 8601 format.

metadatadictionary

Additional information about the event.

Returns

Returns the updated billing metric event object if successful. Returns an error if the event doesn't exist or the update fails.

PATCH/v1/billing/metering_events/:id
curl -X PATCH "https://api.framepayments.com/v1/billing/metering_events/41411633-b804-4cf0-bb75-a9fc2c35b36e" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "value": 29,
    "timestamp": "2025-08-29T09:09:09.062103Z"
  }'
Response
{
  "id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "meter_id": "meter_1234567890",
  "customer_id": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "value": 29.0,
  "timestamp": "2025-08-29T09:09:09.062103Z",
  "metadata": {},
  "object": "billing_metric_event",
  "livemode": false,
  "created": 1735468149,
  "updated": 1735471749
}