Retrieve a subscription usage list

Retrieve all usage records for the merchant account. Results are ordered by usage_date, unlike other list endpoints which order by created_at. You can use the query parameters for:

Filtering	Pagination
Filter the usage records that you want to retrieve, for example, only retrieve records for a specific subscription or billing cycle. Parameters used for filtering: subscription_id subscription_cycle_id from_usage_date to_usage_date	View usage records without loading all of them at once, for example, return a specified number of records per page. Parameters used for pagination: limit page_token

Request​

Query parameters

Query parameters

Possible values: >= 1 and <= 500

Default value: 100

Maximum number of records to return. Used for pagination.

Filter usage records with a usage_date on or after this date and time.

Filter usage records with a usage_date before this date and time.

Filter usages by the ID of the subscription.

Filter usages by the ID of the subscription cycle.

Token for retrieving the next page of results. Used for pagination.

To paginate through results:

1. Make an initial request with the desired limit.
2. The response will include a next_page_token if more results are available.
3. Use that token in the page_token parameter of your next request.
4. Repeat until next_page_token is not present.

Note

When using page_token, you must include all query parameters from the initial request (such as from, to, or other filter parameters) to maintain consistent filtering across pages.

Header parameters

Header parameters

Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"

This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.

It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.

Info

For more information, see: Authentication

Possible values: [2023-09-01, 2024-05-01, 2024-09-01, 2025-10-16, 2025-12-04, 2026-03-12, 2026-04-20]
Example: "2026-04-20"

The version of the Merchant API, specified in YYYY-MM-DD format.

If not specified, you will receive an error.

Info

For more information about API versioning, see: API versions.

Response​

List of subscription usages retrieved successfully

Response body

Body object

Token for retrieving the next page of results. Use this token as the value of the page_token query parameter in your next request to retrieve the next page.

If not present, there are no more results to retrieve.

List of subscription usages.

The unique identifier of the usage record.

Unique identifier for the subscription.

Unique identifier for the subscription cycle.

Possible length: <= 250 characters
Example: "api_calls"

A merchant-defined identifier for a usage-based subscription item. You set this code on each usage item when creating a subscription plan, and supply it when reporting consumption on Create a subscription usage endpoint to target the correct metered item.

This allows a subscription with multiple usage items (e.g., api_calls and storage_gb) to receive consumption reports against the right item without relying on internal IDs.

The code must be unique within a plan phase.

Example: "2026-03-01T21:00:00Z"

The timestamp indicating when the consumption actually occurred.

Constraint	Detail
Format	ISO 8601 date-time string (e.g., YYYY-MM-DDTHH:mm:ssZ).
Timezone	Must be UTC.
Validation	Revolut uses this to identify the applicable billing cycle. Accepted for the active cycle (start_date ≤ usage_date < end_date), for a recently ended cycle before its usage_cutoff_date, and for the one next upcoming cycle. Other dates are rejected.

Example: 100.5

The quantity of consumption to record for this usage report.

Supports up to 20 digits before and 20 digits after the decimal point.

Example:

{
  "user_id": "12345",
  "api_version": "v2",
  "usage_rate": 1.5,
  "is_trial": true
}

Property count: <= 50 properties

Key-value pairs you can attach to a usage record for your own tracking and reporting purposes.

Constraint	Detail
Keys	Maximum 50 keys per record.
Value types	String, number, or boolean only.
Number precision	Up to 20 digits before and 20 digits after the decimal point.

Example: "2026-03-01T21:05:00Z"

The date and time the usage record was created in ISO 8601 format.

Example: "2026-03-01T21:05:00Z"

The date and time the usage record was last updated in ISO 8601 format.