Descontos e cupons

Aplicar desconto em uma cobrança

Dá um desconto pontual, de valor livre, em uma cobrança específica — por exemplo, para negociar uma fatura vencida. Não afeta as outras cobranças.

POST/v1/subscriptions/:subscriptionId/discounts

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Qual cobrança: informe invoiceId, chargeId ou cycleNumber. Sem nenhum deles, vale para a cobrança atual.

O que acontece com a cobrança: se ela já foi emitida em Pix ou boleto, é reemitida com o valor novo (a menos que reissueOpenCharge seja false). O boleto antigo não é cancelado, a menos que você envie cancelOpenBoleto: true. Para remover um desconto, envie discount: null.

O desconto não pode zerar a cobrança. Para benefícios recorrentes ou período grátis, use Aplicar cupom.

Envie dryRun: true para ver o valor novo sem aplicar.

Authorizations

bearer

Authorization

string obrigatório

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

Escopos requeridos

subscriptions/write

Path Parameters

subscriptionIdstringobrigatório

ID da assinatura (ex: sub_xxx) - required

Body

application/json

Content-Type:application/json

JSON

{
    "cycleNumber": 3, 
    "discount": { 
        "type": "PERCENTAGE", 
        "value": 10 
    },
    "reissueOpenCharge": true, 
    "cancelOpenBoleto": false, 
    "reason": "Negociação da fatura", 
    "dryRun": false 
}

Schema

discountobjectobrigatório

Desconto. Envie null para remover o desconto atual

cycleNumbernumberopcional

Ciclo da cobrança. Alternativa: invoiceId ou chargeId

reissueOpenChargebooleanopcional

false: não reemite a cobrança já emitida (padrão true)

cancelOpenBoletobooleanopcional

true: cancela o boleto em aberto ao reemitir

reasonstringopcional

Motivo, gravado no histórico

dryRunbooleanopcional

true: só simula

← Anterior

Aplicar cupom

Atualizar configurações

const url = 'https://sandbox.validapay.com.br/v1/subscriptions/:subscriptionId/discounts';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "cycleNumber": 3, 
    "discount": { 
        "type": "PERCENTAGE", 
        "value": 10 
    },
    "reissueOpenCharge": true, 
    "cancelOpenBoleto": false, 
    "reason": "Negociação da fatura", 
    "dryRun": false 
})
};

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

Response Examples

200▾

JSON

{
    "success": true, 
    "type": "DISCOUNT_APPLIED", 
    "subscriptionId": "sub_xxx", 
    "target": { 
        "kind": "INVOICE", 
        "cycleNumber": 3, 
        "invoiceId": "inv_xxx", 
        "invoiceNumber": "000003", 
        "isPrimaryInvoice": true 
    },
    "discount": { "type": "PERCENTAGE", "value": 10 }, 
    "previousDiscount": null, 
    "grossAmount": 99.9, 
    "discountAmount": 9.99, 
    "currentAmount": 99.9, 
    "newAmount": 89.91, 
    "reissue": { 
        "willReissue": true, 
        "skipReason": null, 
        "paymentType": "BOLETO", 
        "subscriptionPaymentType": "BOLETO", 
        "openChargeId": "cha_xxx" 
    },
    "warnings": [], 
    "reissued": { "chargeId": "cha_yyy", "paymentType": "BOLETO", "dueDate": "2026-10-10", "amount": 89.91 } 
}

Campos da resposta

successboolean

true quando o desconto foi aplicado ou removido

typestring

DISCOUNT_APPLIED, DISCOUNT_REMOVED, NO_CHANGE ou PREVIEW (dryRun)

Valores aceitos:DISCOUNT_APPLIEDDISCOUNT_REMOVEDNO_CHANGEPREVIEW

subscriptionIdstring

ID da assinatura

targetobject

Cobrança que recebeu o desconto

discountobject

Desconto aplicado

previousDiscountobject

Desconto que existia antes

grossAmountnumber

Valor sem desconto, em reais

discountAmountnumber

Valor do desconto, em reais

currentAmountnumber

Valor da cobrança antes, em reais

newAmountnumber

Valor da cobrança depois, em reais

reissueobject

Reemissão da cobrança

warningsarray[0]

Avisos, como boleto antigo que continua pagável

reissuedobject

Nova cobrança emitida com o desconto

400desconto zera a cobrança▾

JSON

{
    "error": {
        "message": "O desconto não pode zerar a cobrança, hoje em 99.90",
        "code": "DISCOUNT_EXCEEDS_CHARGE_AMOUNT",
        "details": null,
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Aplicar cupom

Atualizar configurações