# Aplicar desconto em uma cobrança

**Área:** Descontos e cupons

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`

**Scopes necessários:** `subscriptions/write`

**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.

### Path parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `subscriptionId` | **sim** | ID da assinatura (ex: sub_xxx) - required |

### Request body

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

### Campos do body

**Obrigatórios:** `discount`, `discount.type`, `discount.value`

| Campo | Descrição |
|---|---|
| `discount` | Desconto. Envie null para remover o desconto atual |
| `discount.type` | PERCENTAGE: percentual. FIXED: valor em reais (valores: PERCENTAGE, FIXED) |
| `discount.value` | Percentual (até 100) ou valor em reais |

**Opcionais**

| Campo | Descrição |
|---|---|
| `cycleNumber` | Ciclo da cobrança. Alternativa: invoiceId ou chargeId |
| `reissueOpenCharge` | false: não reemite a cobrança já emitida (padrão true) |
| `cancelOpenBoleto` | true: cancela o boleto em aberto ao reemitir |
| `reason` | Motivo, gravado no histórico |
| `dryRun` | true: só simula |

### Resposta 200: 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

| Campo | Descrição |
|---|---|
| `success` | true quando o desconto foi aplicado ou removido |
| `type` | DISCOUNT_APPLIED, DISCOUNT_REMOVED, NO_CHANGE ou PREVIEW (dryRun) (valores: DISCOUNT_APPLIED, DISCOUNT_REMOVED, NO_CHANGE, PREVIEW) |
| `subscriptionId` | ID da assinatura |
| `target` | Cobrança que recebeu o desconto |
| `target.kind` | INVOICE: fatura já emitida. CYCLE: ciclo ainda não emitido (valores: INVOICE, CYCLE) |
| `target.cycleNumber` | Ciclo da cobrança |
| `target.invoiceId` | Fatura |
| `target.invoiceNumber` | Número da fatura |
| `target.isPrimaryInvoice` | true quando é a fatura principal do ciclo |
| `discount` | Desconto aplicado |
| `previousDiscount` | Desconto que existia antes |
| `grossAmount` | Valor sem desconto, em reais |
| `discountAmount` | Valor do desconto, em reais |
| `currentAmount` | Valor da cobrança antes, em reais |
| `newAmount` | Valor da cobrança depois, em reais |
| `reissue` | Reemissão da cobrança |
| `reissue.willReissue` | true quando a cobrança em aberto é reemitida |
| `reissue.skipReason` | Por que não foi reemitida (valores: NOT_REQUESTED, NO_OPEN_CHARGE, NO_OPEN_DOCUMENT) |
| `reissue.paymentType` | Forma de pagamento da cobrança |
| `reissue.subscriptionPaymentType` | Forma de pagamento da assinatura |
| `reissue.openChargeId` | Cobrança em aberto reemitida |
| `warnings` | Avisos, como boleto antigo que continua pagável |
| `reissued` | Nova cobrança emitida com o desconto |

### Resposta 400: 400 desconto 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"
    }
}
```


---

Página: https://docs.validapay.com.br/referencia/post-aplicar-desconto-em-uma-cobranca  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json