> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Registra uso medido
> Reporta un evento de uso contra una suscripción para que los cargos medidos se agreguen a la próxima factura.
export const SchemaLangNote = ({lang}) => {
const text = ({
es: "Los nombres de campos y el esquema de solicitud/respuesta que se muestran a continuación están en inglés — se generan a partir de la especificación OpenAPI. El texto explicativo de esta página está traducido.",
pt: "Os nomes dos campos e o esquema de requisição/resposta exibidos abaixo estão em inglês — são gerados a partir da especificação OpenAPI. O texto explicativo desta página está traduzido."
})[lang] || "Field names and the request/response schema shown below are in English — they are generated from the OpenAPI specification.";
return {text};
};
Usa `POST /subscription/usage` para reportar el consumo medido contra una suscripción. La facturación por uso te permite cobrar un monto variable además de la tarifa fija del plan — por ejemplo una suscripción base más un cargo por solicitud o por gigabyte.
Los **medidores** de uso y su **tarificación por plan** se configuran en el Dashboard, en **Suscripciones → Medidores de uso**, no por la API. Este endpoint solo ingiere los eventos de uso en bruto. Consulta [Facturación por uso e híbrida](/es/guides/subscriptions#facturación-por-uso-e-híbrida) para el modelo completo.
## Cómo los cargos medidos llegan a una factura
1. Defines un medidor (p. ej. `api_requests`) con un modo de agregación, y lo tarificas en un plan.
2. A lo largo del período de facturación llamas a `POST /subscription/usage` por cada evento de uso.
3. En la renovación, Therius agrega los eventos de ese período según el modo de agregación del medidor, resta las unidades incluidas del plan, aplica el esquema de tarificación y suma el resultado a la factura como su propia [línea](/es/api-reference/subscriptions/invoices#line-items).
El período de facturación al que cuenta un evento se determina por su timestamp `occurredAt`.
Envía un header `Idempotency-Key` opcional cuando tu trabajo de reporte pueda reintentar — una repetición con el mismo par `(meterCode, Idempotency-Key)` devuelve el evento original con `duplicate: true` en vez de registrar un segundo.
```bash cURL theme={"dark"}
curl -X POST https://api.therius.io/v1/subscription/usage \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: batch-2026-09-02T10:00Z" \
-d '{
"subscriptionId": "sub_abc123def456",
"meterCode": "api_requests",
"quantity": 500
}'
```
```json 200 OK theme={"dark"}
{
"id": "3f1c9a2e-8b7d-4e2a-9c31-6a0b5d4e7f88",
"meterCode": "api_requests",
"quantity": 500,
"occurredAt": "2026-09-02T10:00:00Z",
"duplicate": false
}
```
## OpenAPI
````yaml POST /subscription/usage
openapi: 3.1.0
info:
title: Therius API
description: REST API for payments, subscriptions, and billing plans.
version: 1.0.0
servers:
- url: https://api.therius.io/v1
description: Production
- url: https://api-sandbox.therius.io/v1
description: Sandbox
security:
- bearerAuth: []
paths:
/subscription/usage:
post:
tags:
- Subscriptions
summary: Record a metered usage event
description: >-
Report a usage event against a subscription for a meter defined on its
plan. At each renewal Therius aggregates the period's events per the
meter's aggregation mode, prices them, and adds the result to the
invoice. Meters and their per-plan pricing are configured in the
Dashboard (Subscriptions → Usage Meters); this endpoint only ingests the
raw events.
operationId: recordSubscriptionUsage
parameters:
- name: Idempotency-Key
in: header
description: >-
Optional. A replay with the same `(meterCode, Idempotency-Key)` pair
returns the original event instead of recording a second one. Use it
when your reporting job may retry.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- subscriptionId
- meterCode
- quantity
properties:
merchantCode:
type: string
description: Your merchant account identifier.
subscriptionId:
type: string
description: UUID of the subscription the usage is attributed to.
meterCode:
type: string
description: >-
The `code` of a usage meter belonging to your merchant
account, e.g. `api_requests`.
example: api_requests
quantity:
type: number
description: Non-negative quantity for this event, in the meter's units.
example: 500
occurredAt:
type: string
format: date-time
description: >-
Optional RFC 3339 timestamp of when the usage occurred.
Defaults to the time the request is received. Determines
which billing period the event falls into.
responses:
'200':
description: Event recorded, or the original event on an idempotent replay.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: UUID of the usage event.
meterCode:
type: string
description: The meter the event was recorded against.
quantity:
type: number
description: The recorded quantity.
occurredAt:
type: string
format: date-time
description: >-
Timestamp the event was attributed to (the billing-period
key).
duplicate:
type: boolean
description: >-
`true` when this response is an idempotent replay of a
previously recorded event.
'400':
description: >-
Missing or invalid `subscriptionId`, `meterCode`, `quantity`, or
`occurredAt`.
'401':
description: Missing or invalid API key.
'403':
description: Production access is not enabled for this account.
'404':
description: Subscription or meter not found under your merchant account.
'429':
description: Rate limit exceeded.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
prv_sandbox_xxx` (sandbox).
````