> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Registrar uso
> 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.
Registra unidades de uso de um produto avulso (pay-as-you-go) em uma assinatura ativa. O valor correspondente é incluído na próxima cobrança do ciclo.
Requer a permissão `SUBSCRIPTION:CREATE`.
## Como funciona
Diferente do produto principal da assinatura (que tem ciclo fixo), produtos de uso são cobrados de acordo com o consumo real registrado via este endpoint. Cada registro é vinculado à próxima parcela pendente da assinatura.
Use `action: "add"` para adicionar unidades e `action: "subtract"` para estornar unidades já registradas no mesmo ciclo.
## Corpo da requisição
| Campo | Tipo | Obrigatório | Descrição |
| ----------- | ------- | ----------- | ------------------------------------------------------------ |
| `id` | string | Sim | ID da assinatura (`subs_...`) |
| `productId` | string | Sim | ID do produto de uso (`prod_...`) — **não** deve ter ciclo |
| `units` | integer | Sim | Quantidade de unidades (mínimo `1`) |
| `action` | string | Sim | `"add"` para adicionar ou `"subtract"` para remover unidades |
O produto em `productId` deve ser um produto **sem ciclo** (`cycle: null`). Produtos de assinatura (com ciclo) retornam erro.
**Exemplo — adicionar 50 unidades de API calls:**
```json theme={null}
{
"id": "subs_abc123xyz",
"productId": "prod_api_calls",
"units": 50,
"action": "add"
}
```
**Exemplo — estornar 10 unidades:**
```json theme={null}
{
"id": "subs_abc123xyz",
"productId": "prod_api_calls",
"units": 10,
"action": "subtract"
}
```
## Resposta
Retorna o registro de uso criado, já vinculado à próxima parcela do ciclo (`installmentNumber`).
```json theme={null}
{
"data": {
"id": "usgr_abc123xyz",
"subscriptionId": "subs_abc123xyz",
"productId": "prod_api_calls",
"units": 50,
"unitPrice": 100,
"action": "add",
"installmentNumber": 2,
"recordedAt": "2024-12-06T20:10:00.000Z"
},
"success": true,
"error": null
}
```
| Campo | Tipo | Descrição |
| ------------------- | ------- | ------------------------------------------------- |
| `id` | string | ID do registro de uso (`usgr_...`) |
| `subscriptionId` | string | ID da assinatura |
| `productId` | string | ID do produto |
| `units` | integer | Quantidade de unidades registradas |
| `unitPrice` | integer | Preço unitário em centavos no momento do registro |
| `action` | string | `"add"` ou `"subtract"` |
| `installmentNumber` | integer | Número da parcela onde este uso será cobrado |
| `recordedAt` | string | Data/hora do registro |
O valor total cobrado na próxima parcela inclui todos os registros de uso com `action: "add"` menos os com `action: "subtract"` do mesmo ciclo: `Σ(add × unitPrice) − Σ(subtract × unitPrice)`.
## OpenAPI
````yaml POST /subscriptions/record-usage
openapi: 3.1.0
info:
title: API AbacatePay
description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
version: 1.0.0
servers:
- url: https://api.abacatepay.com/v2
description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
/subscriptions/record-usage:
post:
summary: Registrar uso
description: >
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.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
- productId
- units
- action
additionalProperties: false
properties:
id:
type: string
description: Identificador único da assinatura.
example: subs_abc123xyz
productId:
type: string
description: >-
Identificador do produto de uso. Não deve ter ciclo de
cobrança.
example: prod_api_calls
units:
type: integer
minimum: 1
description: Quantidade de unidades a registrar.
example: 50
action:
type: string
enum:
- add
- subtract
description: >-
`add` para acrescentar unidades à próxima cobrança;
`subtract` para estornar unidades já registradas no ciclo.
example: add
responses:
'200':
description: Uso registrado com sucesso.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/SubscriptionUsageRecord'
error:
type: string
nullable: true
example: null
success:
$ref: '#/components/schemas/Success'
'401':
description: Não autorizado. Falha na autenticação.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Token de autenticação inválido ou ausente.
'404':
description: Assinatura ou produto não encontrado.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Subscription not found or not active
'422':
description: >-
Dados inválidos (ex: produto com ciclo enviado em vez de produto
avulso).
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Product must not have a billing cycle
security:
- bearerAuth: []
components:
schemas:
SubscriptionUsageRecord:
type: object
description: Registro de uso de um produto avulso em uma assinatura.
required:
- id
- subscriptionId
- productId
- units
- unitPrice
- action
- installmentNumber
- recordedAt
additionalProperties: false
properties:
id:
type: string
description: Identificador único do registro de uso.
example: usgr_abc123xyz
subscriptionId:
type: string
description: Identificador da assinatura associada.
example: subs_abc123xyz
productId:
type: string
description: Identificador do produto de uso.
example: prod_api_calls
units:
type: integer
description: Quantidade de unidades registradas.
example: 50
unitPrice:
type: integer
description: Preço unitário em centavos no momento do registro.
example: 100
action:
type: string
description: Tipo de ação aplicada ao uso.
enum:
- add
- subtract
example: add
installmentNumber:
type: integer
description: Número da parcela em que este uso será cobrado.
example: 2
recordedAt:
type: string
format: date-time
description: Data e hora do registro.
example: '2024-12-06T20:10:00.000Z'
Success:
type: boolean
description: Se a requisição obteve sucesso ou não.
example: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Todas as requisições devem incluir sua chave de API no header
Authorization usando o formato `Bearer `. Sem esse
header a requisição será rejeitada.
Saiba mais sobre como criar e usar chaves de API na [documentação de
autenticação](/pages/authentication).
````