---
title: "Registrar uso"
method: POST
path: "/subscriptions/record-usage"
---

# Registrar uso

`POST /subscriptions/record-usage`

Registra unidades de uso de um produto avulso (pay-as-you-go) em uma assinatura ativa.

O registro é vinculado à próxima parcela pendente da assinatura e incluído na cobrança do ciclo atual. Use `action: "add"` para acrescentar unidades e `action: "subtract"` para estornar unidades já registradas.

O produto informado em `productId` **não** deve ter ciclo de cobrança. Produtos de assinatura (com ciclo) retornam erro.

## Request body

- object
  - `id` string, required — Identificador único da assinatura.
  - `productId` string, required — Identificador do produto de uso. Não deve ter ciclo de cobrança.
  - `units` integer, required — Quantidade de unidades a registrar.
  - `action` 'add' | 'subtract', required — `add` para acrescentar unidades à próxima cobrança; `subtract` para estornar unidades já registradas no ciclo.

## Response `200`

Uso registrado com sucesso.

- object
  - `data` SubscriptionUsageRecord — Registro de uso de um produto avulso em uma assinatura.
    - `id` string, required — Identificador único do registro de uso.
    - `subscriptionId` string, required — Identificador da assinatura associada.
    - `productId` string, required — Identificador do produto de uso.
    - `units` integer, required — Quantidade de unidades registradas.
    - `unitPrice` integer, required — Preço unitário em centavos no momento do registro.
    - `action` 'add' | 'subtract', required — Tipo de ação aplicada ao uso.
    - `installmentNumber` integer, required — Número da parcela em que este uso será cobrado.
    - `recordedAt` string, date-time, required — Data e hora do registro.
  - `error` string, nullable
  - `success` boolean — Se a requisição obteve sucesso ou não.

## Other responses

- `401` — Não autorizado. Falha na autenticação.
- `404` — Assinatura ou produto não encontrado.
- `422` — Dados inválidos (ex: produto com ciclo enviado em vez de produto avulso).

---

[API](https://skmtc.net/abacatepay/apis/api-abacatepay.md) · [All operations](https://skmtc.net/abacatepay/apis/api-abacatepay/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/abacatepay/api-abacatepay/revisions/6b89a7fa70f5/schema)