Descontos

Um discount define a regra econômica: percentual ou valor fixo, duração, validade, limite de resgates e escopo de produtos. Ele não precisa ter código público. Para permitir que compradores digitem um cupom no checkout, crie um discount_code apontando para o desconto. Cada aplicação concreta é registrada internamente como redemption, com um retrato da regra e do código no momento da cobrança.

Discount vs. Discount Code

Pense em discount como a regra financeira e em discount_code como a forma de entregar essa regra ao comprador.

Recurso	Responsabilidade	Exemplo
`discount`	Define o desconto: percentual ou valor fixo, duração, produtos elegíveis, validade e limite total.	`20% por 3 meses` ou `R$ 20,00 na primeira cobrança`.
`discount_code`	Define o código digitável e suas restrições de uso.	`BLACK20`, exclusivo para um customer, com mínimo de R$ 100,00.

Quando usar cada um

Use discount direto quando a sua aplicação decide aplicar o benefício sem depender de um cupom digitado, como uma negociação comercial, um plano promocional escolhido no admin ou um ajuste automático em uma assinatura.
Use discount_code quando o comprador precisa informar um código no checkout ou quando você quer medir campanhas diferentes usando a mesma regra econômica.
Use vários discount_codes apontando para o mesmo discount quando a regra é igual, mas a distribuição muda: influenciador, campanha, cliente específico ou período promocional.
Crie discounts separados quando a economia muda: percentual diferente, valor fixo diferente, duração diferente ou produtos elegíveis diferentes.

Data Object

{
  "id": "disc_CSKrETSkeoro358J",
  "object": "discount",
  "amount_off": 2000,
  "applies_to": {
    "products": [
      "prod_Nwsde86dZjk2Gu9Z"
    ]
  },
  "created_at": "2026-05-21T12:00:00Z",
  "currency": "brl",
  "duration": "repeating",
  "duration_in_months": 3,
  "expires_at": "2026-06-01T00:00:00Z",
  "is_active": true,
  "livemode": true,
  "max_redemptions": 500,
  "metadata": {},
  "name": "R$ 20 por 3 meses",
  "percent_off_basis_points": null,
  "redemptions_count": 0,
  "starts_at": "2026-05-01T00:00:00Z",
  "type": "fixed",
  "updated_at": "2026-05-21T12:10:00Z",
  "valid": true
}

string

Identificador do desconto. Usa o prefixo disc_*.

string

Sempre "discount".

integer | null

Valor fixo do desconto, em centavos. Vem null quando type é percentage.

object

Escopo de produtos onde o desconto pode ser aplicado.

Show Campos de applies_to

array

IDs dos produtos elegíveis. Quando vazio, o desconto pode ser aplicado a qualquer produto elegível da compra.

string

Data de criação em ISO 8601.

string | null

Moeda do valor fixo em código de 3 letras minúsculas, como brl. Vem null quando type é percentage.

string

Duração do desconto em cobranças recorrentes.

Valor	Descrição
`once`	Aplica o desconto apenas na primeira cobrança.
`repeating`	Aplica o desconto pelo número de meses definido em `duration_in_months`.
`forever`	Aplica o desconto em todas as cobranças.

integer | null

Quantidade de meses quando duration é repeating.

string | null

Data de expiração em ISO 8601. Vem null quando não há expiração.

boolean

true quando o desconto pode ser usado em novas compras.

boolean

true em produção; false em ambiente de teste.

integer | null

Limite total de aplicações do desconto. Vem null quando não há limite.

object

Objeto livre para correlacionar o desconto com o seu sistema. Quando vazio, retorna {}.

string | null

Nome público ou interno do desconto.

integer | null

Percentual do desconto em basis points. Vem null quando type é fixed.

integer

Quantidade de vezes em que o desconto já foi aplicado.

string | null

Data inicial de validade em ISO 8601. Vem null quando o desconto já pode ser usado.

string

Tipo econômico do desconto.

Valor	Descrição
`percentage`	Desconto percentual, definido em `percent_off_basis_points`.
`fixed`	Desconto de valor fixo, definido em `amount_off`.

string | null

Data da última atualização em ISO 8601.

boolean

true quando o desconto está ativo, dentro da janela de validade e abaixo do limite de uso.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Discount vs. Discount Code

Quando usar cada um

Data Object

Operações

​Discount vs. Discount Code

​Quando usar cada um

​Data Object

​Operações

Discount vs. Discount Code

Quando usar cada um

Data Object

Operações