Dashboard

Cupons

Criar Cupom

Cria um cupom de desconto ou de período extra.

POST/v1/coupons
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Um cupom PERCENTAGE ou FIXED desconta valor da cobrança. Um cupom EXTRA_PERIOD soma dias ou meses à data da próxima cobrança da assinatura, sem gerar cobrança no período pulado — por exemplo, um cupom de "1 mês grátis" numa assinatura mensal faz a próxima cobrança ocorrer 2 meses depois da anterior, em vez de 1.

O campo maxCycles controla em quantos ciclos recorrentes o benefício se repete: com maxCycles=3, os 3 próximos ciclos recebem o desconto (ou o período extra); a partir do 4º, a cobrança volta ao normal. Deixe vazio para o cupom valer em todos os ciclos, até a assinatura ser cancelada.

EXTRA_PERIOD exige appliesTo=RECURRING — não se aplica a cobranças avulsas.

Case de uso:

Como SaaS, quero oferecer "2 meses grátis" para quem assina um plano anual, sem mexer no valor cobrado em cada ciclo.

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

products/write

Body

application/json

Content-Type:application/json
JSON
{
  "code": "BEMVINDO10",
  "name": "Cupom de boas-vindas",
  "description": "10% na primeira cobrança",
  "discountType": "PERCENTAGE",
  "discountValue": 10,
  "extraPeriodUnit": "MONTHS",
  "maxCycles": 3,
  "maxRedemptions": 100,
  "minAmount": 50.00,
  "maxDiscount": 30.00,
  "validFrom": "2026-09-01T00:00:00.000Z",
  "validUntil": "2026-12-31T23:59:59.000Z",
  "productIds": ["price_1788364755079_psuecwgdc"],
  "firstTimeOnly": true,
  "appliesTo": "RECURRING"
}

Schema

codestringobrigatório
Código que o cliente digita no checkout para aplicar o cupom (salvo em maiúsculas)
discountTypestringobrigatório
PERCENTAGE desconta % do valor, FIXED desconta um valor fixo em reais, EXTRA_PERIOD soma dias/meses à próxima cobrança em vez de descontar valor
Valores aceitos:PERCENTAGEFIXEDEXTRA_PERIOD
discountValuenumberobrigatório
Percentual (0.01 a 100) para PERCENTAGE, valor em reais para FIXED, quantidade inteira de dias/meses para EXTRA_PERIOD
Regra:0.01
namestringopcional
Nome para identificação interna (default = code)
Regra:até 100 caracteres
descriptionstringopcional
Regra:até 255 caracteres
extraPeriodUnitstringopcional
Obrigatório apenas quando discountType=EXTRA_PERIOD; unidade da quantidade em discountValue
Valores aceitos:DAYSMONTHS
maxCyclesnumberopcional
Quantos ciclos recorrentes recebem o benefício (desconto ou período extra); vazio = todos os ciclos, até a assinatura ser cancelada
Regra:1
maxRedemptionsnumberopcional
Quantas vezes este código pode ser usado no total, somando todos os clientes; vazio = ilimitado
Regra:1
minAmountnumberopcional
Valor mínimo do pedido para o cupom ser aceito; sem efeito em EXTRA_PERIOD
Regra:0.01
maxDiscountnumberopcional
Teto do desconto em reais, útil para limitar cupons PERCENTAGE; sem efeito em FIXED ou EXTRA_PERIOD
Regra:0.01
validFromstringopcional
Cupom só é válido a partir desta data; vazio = válido imediatamente
Regra:date-time
validUntilstringopcional
Cupom deixa de ser aceito após esta data; vazio = sem expiração
Regra:date-time
productIdsarray[1]opcional
Restringe o cupom a price IDs específicos; vazio = todos os produtos
firstTimeOnlybooleanopcional
Cada cliente (por CPF/CNPJ) só pode usar este cupom uma vez (default false)
appliesTostringopcional
Tipo de cobrança em que o cupom é aceito; EXTRA_PERIOD exige RECURRING (default ALL)
Valores aceitos:ALLRECURRINGONE_TIME
const url = 'https://sandbox.validapay.com.br/v1/coupons';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "code": "BEMVINDO10",
  "name": "Cupom de boas-vindas",
  "description": "10% na primeira cobrança",
  "discountType": "PERCENTAGE",
  "discountValue": 10,
  "extraPeriodUnit": "MONTHS",
  "maxCycles": 3,
  "maxRedemptions": 100,
  "minAmount": 50.00,
  "maxDiscount": 30.00,
  "validFrom": "2026-09-01T00:00:00.000Z",
  "validUntil": "2026-12-31T23:59:59.000Z",
  "productIds": ["price_1788364755079_psuecwgdc"],
  "firstTimeOnly": true,
  "appliesTo": "RECURRING"
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

201▾
JSON
{
  "couponId": "coup_1789157079333_fq358baak",
  "accountId": "4231833",
  "code": "BEMVINDO10",
  "name": "Cupom de boas-vindas",
  "description": "10% na primeira cobrança",
  "discountType": "PERCENTAGE",
  "discountValue": 10,
  "extraPeriodUnit": null,
  "maxCycles": 3,
  "maxRedemptions": 100,
  "currentRedemptions": 12,
  "minAmount": 50.0,
  "maxDiscount": 30.0,
  "validFrom": "2026-09-01T00:00:00.000Z",
  "validUntil": "2026-12-31T23:59:59.000Z",
  "productIds": [
    "price_1788364755079_psuecwgdc"
  ],
  "firstTimeOnly": true,
  "appliesTo": "RECURRING",
  "status": "ACTIVE",
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-09-01T10:00:00.000Z"
}
400▾
JSON
{
        "error": {
                "message": "Dados inválidos",
                "code": "VALIDATION_ERROR",
                "details": null,
                "timestamp": "2026-09-11T21:00:00.000Z"
        }
}

← Anterior

Excluir Configuração Fiscal

Próximo →

Listar Cupons