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
POST/v1/billing/metering_eventsGET/v1/billing/metering_events/:idPATCH/v1/billing/metering_events/:id

The Billing Metric Event Object

Attributes
idstringoptional

Unique identifier for the billing metric event.

meter_idstringoptional

The ID of the associated billing meter.

customer_idstringoptional

The ID of the customer this event is associated with.

valuefloatoptional

The measured value for this event.

timestampstringoptional

The time when this event occurred in ISO 8601 format.

metadatadictionaryoptional

Additional information about the event.

objectstringoptional

The object type, always "billing_metric_event".

livemodebooleanoptional

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

createdintegeroptional

Unix timestamp when the event was created.

updatedintegeroptional

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_namestringrequired

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

referencestringrequired

A unique reference for this event.

customerstringrequired

The ID of the customer this event is associated with.

valuefloatrequired

The measured value for this event.

timestampstringoptional

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

metadatadictionaryoptional

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
idstringrequired

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
idstringrequired

The ID of the billing metric event to update.

valuefloatoptional

The new measured value for this event.

timestampstringoptional

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

metadatadictionaryoptional

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
}