Billing Reports

Billing Reports aggregate customer usage data across billing metrics, providing a detailed breakdown of consumption during a billing period. Reports can be generated for a customer, subscription, or specific events.

ENDPOINTS
GET/api/v1/billing/reportsGET/v1/billing/report/subscriptionGET/v1/billing/report/event/:event_nameGET/v1/billing/report/events

The Billing Report Object

Attributes
customerstringoptional

The unique ID for the customer.

usagefloatoptional

Total usage across all billing metrics.

livemodebooleanoptional

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

aggregated_usagearrayoptional

Array of objects detailing usage per event.

Billing Report Object
{
  "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "usage": "18000.0",
  "livemode": false,
  "aggregated_usage": [
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "kyc_requests",
      "usage": "0.0",
      "billing_metric": "f579684e-d442-4b9e-bb69-3e75f6308d1e"
    },
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "frame_gives_you_billing",
      "usage": "18000.0",
      "billing_metric": "41411633-b804-4cf0-bb75-a9fc2c35b36e"
    }
  ]
}

Aggregated Usage Object

Attributes
objectstringoptional

The object type, always "billing_report".

aggregationenumoptional

The aggregation method used (e.g., "sum").

event_namestringoptional

The name of the billing event.

usagestringoptional

The usage amount for this event.

billing_metricstringoptional

The UUID of the billing metric.

Aggregated Usage Object
{
  "object": "billing_report",
  "aggregation": "sum",
  "event_name": "kyc_requests",
  "usage": "0.0",
  "billing_metric": "f579684e-d442-4b9e-bb69-3e75f6308d1e"
}

Generate Billing Report for Customer

Generates a billing report for a specific customer within a given time range.

Parameters
customerstringrequired

The ID of the customer to get the report for.

fromstringrequired

Start date for the report period in ISO 8601 format.

tostringrequired

End date for the report period in ISO 8601 format.

Returns

Returns a billing report object with aggregated usage for the customer.

GET/api/v1/billing/reports
curl "https://api.framepayments.com/api/v1/billing/reports?customer=5c5286be-ca91-47d7-92d1-4f211963fce9&from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z" \
  -H "Authorization: Bearer API_KEY"
Response
{
  "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "usage": "18000.0",
  "livemode": false,
  "aggregated_usage": [
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "kyc_requests",
      "usage": "0.0",
      "billing_metric": "f579684e-d442-4b9e-bb69-3e75f6308d1e"
    },
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "frame_gives_you_billing",
      "usage": "18000.0",
      "billing_metric": "41411633-b804-4cf0-bb75-a9fc2c35b36e"
    }
  ]
}

Generate Billing Report By Subscription

Returns the billing report for a specific subscription in the current subscription period.

Parameters
subscriptionstringrequired

The ID of the subscription to get the report for.

Returns

Returns a billing report object with aggregated usage for the subscription.

GET/v1/billing/report/subscription
curl "https://api.framepayments.com/v1/billing/report/subscription?subscription=5c5286be-ca91-47d7-92d1-4f211963fce9" \
  -H "Authorization: Bearer API_KEY"
Response
{
  "subscription_id": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "usage": "18000.0",
  "livemode": false,
  "aggregated_usage": [
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "kyc_requests",
      "usage": "0.0",
      "billing_metric": "f579684e-d442-4b9e-bb69-3e75f6308d1e"
    },
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "frame_gives_you_billing",
      "usage": "18000.0",
      "billing_metric": "41411633-b804-4cf0-bb75-a9fc2c35b36e"
    }
  ]
}

Generate Report for Event

Generates a report for a specific billing event within a given time range.

Parameters
event_namestringrequired

The name of the billing event to generate the report for.

customerstringrequired

The ID of the customer to get the report for.

start_datestringrequired

Start date for the report period in ISO 8601 format.

end_datestringrequired

End date for the report period in ISO 8601 format.

Returns

Returns a billing report object for the specified event.

GET/v1/billing/report/event/:event_name
curl "https://api.framepayments.com/v1/billing/report/event/bounce_for_it_m0p-p?customer=5c5286be-ca91-47d7-92d1-4f211963fce9&start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z" \
  -H "Authorization: Bearer API_KEY"
Response
{
  "object": "billing_report",
  "aggregation": "sum",
  "event_name": "kyc_requests",
  "usage": "330.0",
  "billing_metric": "f579684e-d442-4b9e-bb69-3e75f6308d1e",
  "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "livemode": false
}

Generate Report for Events (Bulk)

Generates reports for multiple billing events within a given time range.

Parameters
customerstringrequired

The ID of the customer to get the report for.

start_datestringrequired

Start date for the report period in ISO 8601 format.

end_datestringrequired

End date for the report period in ISO 8601 format.

eventsstringrequired

Comma-separated list of event names to include in the report.

Returns

Returns a billing report object with aggregated usage for the specified events.

GET/v1/billing/report/events
curl "https://api.framepayments.com/v1/billing/report/events?customer=5c5286be-ca91-47d7-92d1-4f211963fce9&start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z&events=kyc_requests,frame_gives_you_billing" \
  -H "Authorization: Bearer API_KEY"
Response
{
  "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "usage": "18000.0",
  "livemode": false,
  "aggregated_usage": [
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "kyc_requests",
      "usage": "0.0",
      "billing_metric": "f579684e-d442-4b9e-bb69-3e75f6308d1e"
    },
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "frame_gives_you_billing",
      "usage": "18000.0",
      "billing_metric": "41411633-b804-4cf0-bb75-a9fc2c35b36e"
    }
  ]
}