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

# Create a subscription usage

Report a unit of consumption against a usage-based subscription item. Revolut accumulates reported records throughout the billing cycle and processes the charge after the cycle's `usage_cutoff_date`.

### Resolve the billing cycle

Revolut automatically identifies the applicable billing cycle from the `usage_date` you provide. The following submission windows are accepted:

| Window | Rule |
| ------ | ---- |
| Active cycle | `usage_date` falls within the current cycle (`start_date ≤ usage_date < end_date`). |
| Past cycle correction | `usage_date` falls within a recently ended cycle, and the request is made before that cycle's `usage_cutoff_date` (12 hours after `end_date` by default). |
| Next upcoming cycle | `usage_date` falls within the one next future cycle. Revolut creates a `pending` cycle to hold the record until it becomes active. |

Any `usage_date` outside these windows causes the request to be rejected.

### How Revolut calculates the charge

After the `usage_cutoff_date` passes, all records for each usage item are aggregated using the method defined on the subscription plan:

| Method | Behaviour |
| ------ | --------- |
| `sum` | Totals all reported values during the cycle. Use for cumulative metrics (e.g., total GB transferred). |
| `latest` | Uses the most recently reported value at the `usage_cutoff_date`. If no usages are reported during the cycle, the charge is 0. Use for gauge-style metrics (e.g., active seat count at month-end). |
| `max` | Uses the highest value reported during the cycle. Use for capacity-based billing (e.g., peak concurrent connections). |

The aggregated total is multiplied by the unit price to produce the final charge.

:::warning
The `Idempotency-Key` header is **required** for this endpoint. Providing a unique idempotency key ensures that duplicate requests due to retries or network issues do not result in duplicate usage records.
:::

## Endpoint

POST `/api/subscription-usages`

## Parameters

### header parameters

- `Idempotency-Key` (string, required)
  The `Idempotency-Key` ensures that requests are processed only once, preventing multiple executions of the same operation due to retries or duplicate requests.
  
  This header is required. It can accept any unique string value the merchant uses.
  
  A recommended practice is to use a unique identifier from your system (such as the entity's ID or a request UUID) as the idempotency key. This facilitates tracking and managing requests effectively.

## Request body

### Attributes

- `subscription_id` (string)
    Unique identifier for the subscription.
- `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-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](https://en.wikipedia.org/wiki/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. |

## Returns

### 201

Usage reported 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-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](https://en.wikipedia.org/wiki/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 |
| 422 | Unprocessable entity (business rule violation) |