Skip to main content
POST
Registrar uso
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

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:
Exemplo — estornar 10 unidades:

Resposta

Retorna o registro de uso criado, já vinculado à próxima parcela do ciclo (installmentNumber).
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