---
api: 'Merchant API'
---

# 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. <br/><br/>Parameters used for filtering:<br/><ul><li>`subscription_id`</li><li>`subscription_cycle_id`</li><li>`from_usage_date`</li><li>`to_usage_date`</li></ul> | View usage records without loading all of them at once, for example, return a specified number of records per page. <br/><br/>Parameters used for pagination:<br/><ul><li>`limit`</li><li>`page_token`</li></ul> |

## Endpoint

GET `/api/subscription-usages`

## Parameters

### query parameters

- `limit` (integer, optional)
  Maximum number of records to return. Used for **pagination**.

- `from_usage_date` (string, optional)
  Filter usage records with a `usage_date` on or after this date and time.

- `to_usage_date` (string, optional)
  Filter usage records with a `usage_date` before this date and time.

- `subscription_id` (string, optional)
  Filter usages by the ID of the subscription.

- `subscription_cycle_id` (string, optional)
  Filter usages by the ID of the subscription cycle.

- `page_token` (string, optional)
  Token for retrieving the next page of results. Used for **pagination**.
  
  To paginate through results:
  
    1. Make an initial request with the desired `limit`.
    1. The response will include a `next_page_token` if more results are available.
    1. Use that token in the `page_token` parameter of your next request.
    1. 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.
  :::

## Returns

### 200

List of subscription usages retrieved successfully

#### Response attributes

- `next_page_token` (string | null, optional)
    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.
- `subscription_usages` (array of object, optional)
    List of subscription usages.
  - `subscription_usages[].id` (string)
      The unique identifier of the usage record.
  - `subscription_usages[].subscription_id` (string)
      Unique identifier for the subscription.
  - `subscription_usages[].subscription_cycle_id` (string)
      Unique identifier for the subscription cycle.
  - `subscription_usages[].subscription_item_code` (string)
      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](/docs/api/merchant#create-a-subscription-usage) 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.
  - `subscription_usages[].usage_date` (string)
      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. |
  - `subscription_usages[].quantity` (number)
      The quantity of consumption to record for this usage report. 
      
      Supports up to 20 digits before and 20 digits after the decimal point.
  - `subscription_usages[].metadata` (object, optional)
      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. |
  - `subscription_usages[].created_at` (string)
      The date and time the usage record was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `subscription_usages[].updated_at` (string)
      The date and time the usage record was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |