Skip to main content
POST
/
subscriptions
/
record-usage
Registrar uso
curl --request POST \
  --url https://api.abacatepay.com/v2/subscriptions/record-usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "subs_abc123xyz",
  "productId": "prod_api_calls",
  "units": 50,
  "action": "add"
}
'
{
  "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"
  },
  "error": null,
  "success": true
}
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

CampoTipoObrigatórioDescrição
idstringSimID da assinatura (subs_...)
productIdstringSimID do produto de uso (prod_...) — não deve ter ciclo
unitsintegerSimQuantidade de unidades (mínimo 1)
actionstringSim"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: 
{
  "id": "subs_abc123xyz",
  "productId": "prod_api_calls",
  "units": 50,
  "action": "add"
}
Exemplo — estornar 10 unidades: 
{
  "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). 
{
  "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
}
CampoTipoDescrição
idstringID do registro de uso (usgr_...)
subscriptionIdstringID da assinatura
productIdstringID do produto
unitsintegerQuantidade de unidades registradas
unitPriceintegerPreço unitário em centavos no momento do registro
actionstring"add" ou "subtract"
installmentNumberintegerNúmero da parcela onde este uso será cobrado
recordedAtstringData/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).

Authorizations

​
Authorization
string
header
required

Todas as requisições devem incluir sua chave de API no header Authorization usando o formato Bearer <abacatepay-api-key>. Sem esse header a requisição será rejeitada.

Saiba mais sobre como criar e usar chaves de API na documentação de autenticação.

Body

application/json
​
id
string
required

Identificador único da assinatura.

Example:

"subs_abc123xyz"

​
productId
string
required

Identificador do produto de uso. Não deve ter ciclo de cobrança.

Example:

"prod_api_calls"

​
units
integer
required

Quantidade de unidades a registrar.

Required range: x >= 1
Example:

50

​
action
enum<string>
required

add para acrescentar unidades à próxima cobrança; subtract para estornar unidades já registradas no ciclo.

Available options:
add,
subtract
Example:

"add"

Response

Uso registrado com sucesso.

​
data
object

Registro de uso de um produto avulso em uma assinatura.

​
error
string | null
Example:

null

​
success
boolean

Se a requisição obteve sucesso ou não.

Example:

true