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

# Retrieve a subscription usage

Retrieve a usage record by its unique identifier.

Use this endpoint to get the details of a specific usage that was reported or updated.

## Endpoint

GET `/api/subscription-usages/{usage_id}`

## Returns

### 200

Usage record retrieved successfully

#### Response attributes

- `id` (string)
    The unique identifier of the usage record.
- `subscription_id` (string)
    Unique identifier for the subscription.
- `subscription_cycle_id` (string)
    Unique identifier for the subscription cycle.
- `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.
- `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. |
- `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.
- `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. |
- `created_at` (string)
    The date and time the usage record was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- `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 |
| 404 | Usage not found |