Pagamento

Trocar dia de vencimento

Muda o dia do mês em que a assinatura vence. O dia novo sempre vale para as próximas cobranças; você escolhe o que acontece com a cobrança atual e com a diferença de dias.

PUT/v1/subscriptions/:subscriptionId/due-date

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

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

applyFrom: CURRENT_CYCLE e prorata: true — a cobrança atual é reemitida na nova data, com a diferença de dias (a mais ao adiar, a menos ao antecipar).
applyFrom: CURRENT_CYCLE e prorata: false — a cobrança atual é reemitida na nova data, com o mesmo valor.
applyFrom: NEXT_CYCLE e prorata: true — a cobrança atual não muda; a diferença de dias entra na próxima cobrança.
applyFrom: NEXT_CYCLE e prorata: false — só muda o dia a partir da próxima cobrança, sem diferença de valor.

Diferença de dias (pró-rata): adiar o vencimento aumenta o período coberto, então o cliente paga pelos dias a mais; antecipar reduz o período, e os dias a menos viram desconto.

Boleto em aberto não é cancelado ao reemitir, a menos que você envie cancelOpenBoleto: true. No cartão a cobrança não é reemitida; o dia novo vale a partir das próximas.

Envie dryRun: true para ver as datas e os valores sem alterar nada.

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

{
    "billingDay": 20, 
    "applyFrom": "NEXT_CYCLE", 
    "prorata": true, 
    "currentChargeDueDate": "2026-09-30", 
    "cancelOpenBoleto": false, 
    "reason": "Pedido do cliente", 
    "dryRun": false 
}

Schema

billingDaynumberobrigatório

Novo dia de vencimento (1 a 31)

Regra:1 a 31

applyFromstringopcional

CURRENT_CYCLE: reemite a cobrança atual. NEXT_CYCLE: a cobrança atual não muda (padrão CURRENT_CYCLE)

Valores aceitos:CURRENT_CYCLENEXT_CYCLE

proratabooleanopcional

true: cobra ou desconta a diferença de dias. false: só muda a data (padrão true)

currentChargeDueDatestringopcional

Novo vencimento da cobrança atual (YYYY-MM-DD). Só com CURRENT_CYCLE

cancelOpenBoletobooleanopcional

true: cancela o boleto em aberto ao reemitir. Só com CURRENT_CYCLE

reasonstringopcional

Motivo, gravado no histórico

dryRunbooleanopcional

true: só simula

← Anterior

Trocar cartão ou método de pagamento

Aplicar cupom

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

const options = {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "billingDay": 20, 
    "applyFrom": "NEXT_CYCLE", 
    "prorata": true, 
    "currentChargeDueDate": "2026-09-30", 
    "cancelOpenBoleto": false, 
    "reason": "Pedido do cliente", 
    "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": "DUE_DATE_CHANGED", 
    "subscriptionId": "sub_xxx", 
    "currentBillingDay": 10, 
    "newBillingDay": 20, 
    "currentNextDueDate": "2026-10-10", 
    "newNextDueDate": "2026-10-20", 
    "currentChargeDueDate": "2026-09-30", 
    "newChargeDueDate": "2026-09-30", 
    "deltaDays": 10, 
    "daysInCycle": 30, 
    "dailyRate": 3.33, 
    "recurringAmount": 99.9, 
    "prorataAmount": 33.3, 
    "prorataApplied": true, 
    "prorataWindow": { "startDate": "2026-10-10", "endDate": "2026-10-19" }, 
    "currentAmount": 99.9, 
    "newChargeAmount": 99.9, 
    "adjustmentTarget": "NEXT_CYCLE", 
    "adjustments": [ { "cycleNumber": 3, "amount": 33.3 } ], 
    "issuesImmediately": false, 
    "reissue": { 
        "willReissue": false, 
        "skipReason": "NOT_REQUESTED", 
        "paymentType": "BOLETO", 
        "openChargeId": null 
    },
    "warnings": [], 
    "updatedCycles": [ { "cycleNumber": 3, "chargeDate": "2026-10-20", "previousChargeDate": "2026-10-10" } ], 
    "issuedCycles": [], 
    "reissued": null, 
    "restoredStatus": null 
}

Campos da resposta

successboolean

true quando o vencimento foi alterado

typestring

DUE_DATE_CHANGED: alterado. NO_CHANGE: nada mudou. PREVIEW: simulação (dryRun)

Valores aceitos:DUE_DATE_CHANGEDNO_CHANGEPREVIEW

subscriptionIdstring

ID da assinatura

currentBillingDaynumber

Dia de vencimento anterior

newBillingDaynumber

Dia de vencimento novo

currentNextDueDatestring

Data da próxima cobrança antes da troca

Regra:date

newNextDueDatestring

Data da próxima cobrança depois da troca

Regra:date

currentChargeDueDatestring

Vencimento da cobrança atual antes da troca

Regra:date

newChargeDueDatestring

Vencimento da cobrança atual depois da troca

Regra:date

deltaDaysnumber

Diferença de dias: positiva ao adiar, negativa ao antecipar

daysInCyclenumber

Dias considerados em um ciclo para o cálculo

dailyRatenumber

Valor de um dia do plano, em reais

recurringAmountnumber

Valor recorrente da assinatura, em reais

prorataAmountnumber

Diferença cobrada (positiva) ou descontada (negativa), em reais. 0 com prorata false

prorataAppliedboolean

false quando a diferença de dias não foi cobrada nem descontada

prorataWindowobject

Dias que geraram a diferença

currentAmountnumber

Valor da cobrança atual antes da troca, em reais

newChargeAmountnumber

Valor da cobrança atual depois da troca, em reais

adjustmentTargetstring

Onde entra a diferença

Valores aceitos:CURRENT_CYCLENEXT_CYCLENONE

adjustmentsarray[1]

Ajustes lançados em cada ciclo, em reais

issuesImmediatelyboolean

true quando a próxima cobrança já entra na janela de emissão e sai agora

reissueobject

Reemissão da cobrança atual

warningsarray[0]

Avisos, como boleto antigo que continua pagável

updatedCyclesarray[1]

Ciclos agendados que mudaram de data

issuedCyclesarray[0]

Ciclos cuja cobrança foi emitida por causa da nova data

reissuedobject

Cobrança reemitida na nova data, com CURRENT_CYCLE

restoredStatusobject

ACTIVE quando a troca tirou a assinatura da inadimplência

400dia inválido▾

JSON

{
    "error": {
        "message": "billingDay deve estar entre 1 e 31",
        "code": "INVALID_DATA",
        "details": null,
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Trocar cartão ou método de pagamento

Aplicar cupom