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

The Billing Report Object

Attributes
customerstring

The unique ID for the customer.

usagefloat

Total usage across all billing metrics.

livemodeboolean

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

aggregated_usagearray

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
objectstring

The object type, always "billing_report".

aggregationenum

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

event_namestring

The name of the billing event.

usagestring

The usage amount for this event.

billing_metricstring

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
customerREQUIREDstring

The ID of the customer to get the report for.

fromREQUIREDstring

Start date for the report period in ISO 8601 format.

toREQUIREDstring

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
subscriptionREQUIREDstring

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_nameREQUIREDstring

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

customerREQUIREDstring

The ID of the customer to get the report for.

start_dateREQUIREDstring

Start date for the report period in ISO 8601 format.

end_dateREQUIREDstring

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
customerREQUIREDstring

The ID of the customer to get the report for.

start_dateREQUIREDstring

Start date for the report period in ISO 8601 format.

end_dateREQUIREDstring

End date for the report period in ISO 8601 format.

eventsREQUIREDstring

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"
    }
  ]
}