Esquema
| Campo | Tipo | Descrição |
|---|
couponId | UUIDv7 | Identificador único |
externalRef | string | ID do cupom no Stripe (único) |
code | string | Código único, máx 40 |
name | string | Nome de exibição, máx 255 |
type | enum | FIXED (centavos), PERCENTAGE |
amount | integer | Valor do desconto |
currency | enum | Moeda |
duration | enum | ONCE, REPEATING |
durationInMonths | integer? | Para REPEATING |
maxRedemptions | integer? | Máximo de usos |
redeemBy | datetime? | Data de expiração |
timesRedeemed | integer | Contador de usos |
amountRedeemed | integer | Total de desconto concedido |
status | enum | ACTIVE, DEPLETED, EXPIRED |
createdBy | UUIDv7 | Criador |
createdAt | datetime | Criação |
updatedBy | UUIDv7 | Último atualizador |
updatedAt | datetime | Última atualização |
deletedBy | UUIDv7? | Quem deletou |
deletedAt | datetime? | Soft delete |
O campo amount tem significado diferente dependendo do type: para FIXED, é o valor absoluto em centavos (ex: 5000 = R$50,00); para PERCENTAGE, é o percentual inteiro (ex: 20 = 20% de desconto).
Transições de Estado
Relacionamentos
- Has many CouponUsages
- Has many SubscriptionCoupons
Regras de Negócio
code globalmente único- FIXED = desconto absoluto em centavos; PERCENTAGE = valor percentual
- ONCE = aplica em uma única invoice por organização; REPEATING = aplica por ciclo de cobrança
- Sincronizado com o Stripe
Use ONCE para promoções de primeira compra e REPEATING com durationInMonths para retenção de clientes. Um cupom REPEATING com durationInMonths: 3 aplica o desconto nos próximos 3 ciclos de cobrança.
O campo maxRedemptions é global — conta o total de organizações que usaram o cupom, não o número de invoices. Uma vez atingido, o status muda para DEPLETED automaticamente.
Exemplo
[
{
"couponId": "019526b2-4d50-7a6e-c5f3-9b1d7f3a5c8e",
"externalRef": "coupon_1AbCdEfGhIjKlMn",
"code": "BEMVINDO2026",
"name": "Boas-vindas 2026",
"type": "PERCENTAGE",
"amount": 20,
"currency": "BRL",
"duration": "REPEATING",
"durationInMonths": 3,
"maxRedemptions": 500,
"redeemBy": "2026-06-30T23:59:59Z",
"timesRedeemed": 127,
"amountRedeemed": 762300,
"status": "ACTIVE",
"createdBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"createdAt": "2026-01-01T00:00:00Z",
"updatedBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"updatedAt": "2026-03-15T10:00:00Z"
},
{
"couponId": "019526b3-5e61-7b7f-d6a4-0c2e8a4b6d9f",
"externalRef": "coupon_2BcDeFgHiJkLmNo",
"code": "DESCONTO50",
"name": "Desconto fixo R$50",
"type": "FIXED",
"amount": 5000,
"currency": "BRL",
"duration": "ONCE",
"durationInMonths": null,
"maxRedemptions": 100,
"redeemBy": "2026-03-31T23:59:59Z",
"timesRedeemed": 100,
"amountRedeemed": 500000,
"status": "DEPLETED",
"createdBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"createdAt": "2026-01-15T00:00:00Z",
"updatedBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
"updatedAt": "2026-03-20T16:45:00Z"
}
]
