Skip to main content
Um cupom representa um codigo de desconto que pode ser aplicado a assinaturas. Cupons suportam descontos de valor fixo ou percentual, podem ser de uso unico ou recorrentes por multiplos ciclos de cobranca, e rastreiam limites de resgate e datas de expiracao. Voce encontrara objetos de cupom ao verificar disponibilidade de desconto ou visualizar descontos aplicados em uma assinatura.
​
couponId
string
O identificador unico do cupom (UUIDv7).
​
externalRef
string
A referencia externa do cupom.
​
code
string
O codigo do cupom usado para resgate.
​
name
string
O nome de exibicao do cupom.
​
type
string
O tipo de desconto. Um de: FIXED, PERCENTAGE.
​
amount
integer
O valor do desconto. Para tipo FIXED, o valor em centavos. Para tipo PERCENTAGE, o valor percentual.
​
currency
string
O codigo da moeda (ex.: BRL, USD).
​
duration
string
Por quanto tempo o desconto se aplica. Um de: ONCE, REPEATING.
​
durationInMonths
integer|null
O numero de meses que o desconto se aplica quando a duracao e REPEATING.
​
maxRedemptions
integer|null
O numero maximo de vezes que este cupom pode ser resgatado. Null para ilimitado.
​
redeemBy
string|null
O prazo para resgatar este cupom (ISO 8601). Null se sem prazo.
​
timesRedeemed
integer
O numero de vezes que este cupom foi resgatado.
​
amountRedeemed
integer
O valor total resgatado ate o momento.
​
status
string
O status do cupom. Um de: ACTIVE, DEPLETED, EXPIRED.
​
createdBy
string
O agente que criou o cupom.
​
createdAt
string
Timestamp de criacao (ISO 8601).
​
updatedBy
string
O agente que atualizou o cupom por ultimo.
​
updatedAt
string
Timestamp da ultima atualizacao (ISO 8601).
{
  "couponId": "019525fd-d3a4-7baf-a7c3-9d1e3f5b7c9f",
  "externalRef": "cpn_1Oy2pL2eZvKYlo2C0vIqMZ8y",
  "code": "WELCOME20",
  "name": "Welcome Discount",
  "type": "PERCENTAGE",
  "amount": 20,
  "currency": "BRL",
  "duration": "REPEATING",
  "durationInMonths": 3,
  "maxRedemptions": 100,
  "redeemBy": "2026-12-31T23:59:59.000Z",
  "timesRedeemed": 42,
  "amountRedeemed": 0,
  "status": "ACTIVE",
  "createdBy": "019525fd-56a8-7db4-8c3e-2a1b4d6f8e0c",
  "createdAt": "2026-01-10T08:00:00.000Z",
  "updatedBy": "019525fd-56a8-7db4-8c3e-2a1b4d6f8e0c",
  "updatedAt": "2026-03-15T16:45:00.000Z"
}