---
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.

## Endpoint

POST `/api/subscription-usages`

## 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-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. |

## 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-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 |
| 422 | Unprocessable entity (business rule violation) |