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.

Request

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.

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.

Request body

Body object

Unique identifier for the subscription.

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.

Response

Usage reported successfully

Response body

Body object

The unique identifier of the usage record.

Unique identifier for the subscription.

Unique identifier for the subscription cycle.