# Atualizar configurações

**Área:** Configurações

Altera as configurações da assinatura: emissão e prazo das cobranças, formas de pagamento aceitas, repasse de taxas, nota fiscal, e-mails em cópia e instruções de boleto e Pix. Envie só os campos que quer mudar.

`PATCH /v1/subscriptions/:subscriptionId`

**Base URL Produção:** `https://api.validapay.com.br`  
**Base URL Sandbox:** `https://sandbox.validapay.com.br`

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

**O que acontece com a cobrança:** as mudanças valem para as próximas cobranças emitidas; cobranças já emitidas não mudam.

> Quando o corpo traz instruções e configurações juntas, a resposta é a das configurações.

### Path parameters

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

### Request body

```json
{
    "issueDaysBeforeDue": 5, 
    "expirationAfterDueDate": 30, 
    "allowConcurrentCycles": false, 
    "passFeesToCustomer": false, 
    "nfConfigId": null, 
    "allowedPaymentMethods": ["creditcard", "pix", "boleto"], 
    "additionalEmails": ["financeiro@empresa.com"], 
    "boletoInstructions": { 
        "fine": 2.0, 
        "interest": 1.0 
    }
}
```

### Campos do body

**Opcionais**

| Campo | Descrição |
|---|---|
| `issueDaysBeforeDue` | Dias antes do vencimento em que o boleto ou Pix é emitido (0 a 60). null volta ao padrão |
| `expirationAfterDueDate` | Dias depois do vencimento em que ainda pode ser paga (0 a 60) |
| `allowConcurrentCycles` | true: permite cobrar um ciclo novo com outro em aberto |
| `passFeesToCustomer` | true: repassa as taxas do cartão ao cliente |
| `nfConfigId` | Configuração de nota fiscal. null desliga a emissão |
| `allowedPaymentMethods` | Formas de pagamento aceitas na fatura (valores: creditcard, pix, boleto, pix_automatico) |
| `additionalEmails` | E-mails em cópia (até 5) |
| `boletoInstructions` | Multa, juros e desconto do boleto. null remove |
| `boletoInstructions.fine` | Multa por atraso, em % |
| `boletoInstructions.interest` | Juros ao mês, em % |

### Resposta 200: 200 configurações

```json
{
    "success": true, 
    "type": "SETTINGS_UPDATED", 
    "subscriptionId": "sub_xxx", 
    "settings": { 
        "issueDaysBeforeDue": 5, 
        "expirationAfterDueDate": 30, 
        "allowConcurrentCycles": false, 
        "passFeesToCustomer": false, 
        "nfConfigId": null, 
        "allowedPaymentMethods": ["creditcard", "pix", "boleto"], 
        "additionalEmails": [] 
    }
}
```

#### Campos da resposta

| Campo | Descrição |
|---|---|
| `success` | true quando as configurações foram salvas |
| `type` | Configurações alteradas |
| `subscriptionId` | ID da assinatura |
| `settings` | Configurações depois da alteração |
| `settings.issueDaysBeforeDue` | Dias antes do vencimento em que a cobrança é emitida |
| `settings.expirationAfterDueDate` | Dias depois do vencimento em que ainda pode ser paga |
| `settings.allowConcurrentCycles` | true: permite cobrar um ciclo novo com outro em aberto |
| `settings.passFeesToCustomer` | true: repassa as taxas do cartão ao cliente |
| `settings.nfConfigId` | Configuração de nota fiscal |
| `settings.allowedPaymentMethods` | Formas de pagamento aceitas na fatura |
| `settings.additionalEmails` | E-mails em cópia |

### Resposta 200: 200 instruções de boleto e Pix

```json
{
    "success": true,
    "subscriptionId": "sub_xxx",
    "boletoInstructions": { "fine": 2.0, "interest": 1.0 } 
}
```

#### Campos da resposta

| Campo | Descrição |
|---|---|
| `boletoInstructions` | Instruções de boleto salvas |

### Resposta 400: 400 sem campos

```json
{
    "error": {
        "message": "Informe ao menos um campo: boletoInstructions, pixInstructions, issueDaysBeforeDue, expirationAfterDueDate, allowConcurrentCycles, passFeesToCustomer, nfConfigId, allowedPaymentMethods, additionalEmails",
        "code": "INVALID_DATA",
        "details": null,
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}
```


---

Página: https://docs.validapay.com.br/referencia/patch-atualizar-configuracoes  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json