Events

Get usage by meter

Changed on

Use when showing usage for a specific meter (e.g. dashboard or overage check). Supports time range, filters, and grouping by customer or subscription.

post/events/usage/meter

Request

  • Base URL
    https://us.api.flexprice.io/v1
  • URL
    https://us.api.flexprice.io/v1/events/usage/meter
  • Auth
    API key in header x-api-key

Request body

billing_anchorstring date-time

BillingAnchor enables custom monthly billing periods for meter usage aggregation.

Usage guidelines:

  • Only effective when WindowSize = "MONTH"
  • For other window sizes (DAY, HOUR, WEEK), this field is ignored
  • When nil, uses standard calendar months (1st to 1st)
  • When provided, creates custom monthly periods (e.g., 5th to 5th)

Common use cases:

  • Subscription billing periods that don't align with calendar months
  • Customer-specific billing cycles (e.g., signed up on 15th)
  • Multi-tenant systems with different billing anchor dates

Example: If BillingAnchor = "2024-03-05T14:30:45Z" and WindowSize = "MONTH":

  • March period: 2024-03-05 14:30:45 to 2024-04-05 14:30:45
  • April period: 2024-04-05 14:30:45 to 2024-05-05 14:30:45
bucket_size'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH'
customer_idstring
end_timestring date-time
external_customer_idstring
filtersobject
meter_idstring required
start_timestring date-time
timezonestring
window_size'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH'

Example request

{
  "billing_anchor": "2024-03-05T14:30:45Z",
  "customer_id": "customer456",
  "end_time": "2024-12-09T00:00:00Z",
  "external_customer_id": "user_5",
  "meter_id": "123",
  "start_time": "2024-11-09T00:00:00Z"
}

Response

OK

event_namestring
type'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM'
valuenumber

Changes

  • f8ecf435d25dRevision changes
    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

  • 646d6658479bRevision changes
    • breaking

      the request property format changed from no format to date-time

    • breaking

      the request property format changed from no format to date-time

    • breaking

      the request property format changed from no format to date-time