Dashboard

Descontos e cupons

Pular uma cobrança

Isenta o cliente de uma cobrança da assinatura, por exemplo para dar um mês de brinde. A assinatura continua normalmente e a cobrança seguinte acontece na data de sempre.

POST/v1/subscriptions/:subscriptionId/cycles/:cycleNumber/skip
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Cada chamada pula um ciclo. Para pular mais de um, faça uma chamada por ciclo.

O que acontece: o Pix ou boleto dessa cobrança é cancelado e o cliente não paga por ela. Ele não recebe aviso.

Não dá para pular uma cobrança já paga, de assinatura em Pix Automático ou de assinatura que ainda não começou. Para dar dias grátis no início, use o período de teste.

Case de uso: Como lojista, quero dar o mês de dezembro de brinde a um assinante, para que ele não seja cobrado e a assinatura continue em janeiro.

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
cycleNumberstringobrigatório
Número do ciclo a pular (ex: 3) - required

Body

application/json

Content-Type:application/json
JSON
{
    "reason": "Mês de brinde", 
    "dryRun": false 
}

Schema

reasonstringopcional
Motivo, gravado no histórico. De 3 a 300 caracteres. Obrigatório sem dryRun
dryRunbooleanopcional
true: só mostra o que vai acontecer, sem pular
const url = 'https://sandbox.validapay.com.br/v1/subscriptions/:subscriptionId/cycles/:cycleNumber/skip';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "reason": "Mês de brinde", 
    "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": "CYCLE_SKIPPED", 
    "subscriptionId": "sub_xxx", 
    "cycleNumber": 3, 
    "skip": { 
        "skippedAt": "2026-10-28T14:20:00.000Z", 
        "skippedBy": "usr_xxx", 
        "skippedByName": null, 
        "reason": "Mês de brinde", 
        "previousStatus": "AWAITING_PAYMENT", 
        "canceledChargeIds": ["cha_xxx"] 
    },
    "canceledCharges": [ 
        {
            "chargeId": "cha_xxx", 
            "invoiceId": "inv_xxx", 
            "paymentType": "BOLETO", 
            "amount": 99.9, 
            "status": "AWAITING_PAYMENT", 
            "dueDate": "2026-11-10", 
            "nfStatus": null, 
            "notas": { "canceled": 0, "flagged": 0, "failed": 0, "untouched": 0 } 
        }
    ],
    "movedAdjustments": 0, 
    "nextCycle": { 
        "cycleNumber": 4, 
        "chargeDate": "2026-12-10", 
        "amount": 99.9 
    },
    "restoredStatus": null 
}

Campos da resposta

successboolean
true quando a cobrança foi pulada
typestring
CYCLE_SKIPPED, ou PREVIEW com dryRun
Valores aceitos:CYCLE_SKIPPEDPREVIEW
subscriptionIdstring
ID da assinatura
cycleNumbernumber
Ciclo pulado
skipobject
Registro do pulo. Também aparece em billingCycles[].cycle.skip de Ver uma assinatura
canceledChargesarray[1]
Cobranças em aberto que foram canceladas
movedAdjustmentsnumber
Ajustes de pró-rata que passaram para o próximo ciclo
nextCycleobject
Próximo ciclo, já criado
restoredStatusobject
ACTIVE quando a assinatura saiu da inadimplência com o pulo
Valores aceitos:ACTIVE
200prévia (dryRun)▾
JSON
{
    "success": true, 
    "type": "PREVIEW", 
    "subscriptionId": "sub_xxx", 
    "cycleNumber": 3, 
    "chargeDate": "2026-11-10", 
    "amount": 99.9, 
    "chargesToCancel": [ 
        {
            "chargeId": "cha_xxx", 
            "invoiceId": "inv_xxx", 
            "paymentType": "BOLETO", 
            "amount": 99.9, 
            "status": "AWAITING_PAYMENT", 
            "dueDate": "2026-11-10", 
            "nfStatus": null 
        }
    ],
    "movedAdjustments": 0, 
    "nextCycle": { 
        "cycleNumber": 4, 
        "chargeDate": "2026-12-10", 
        "alreadyExists": false 
    }
}

Campos da resposta

successboolean
true quando a prévia foi gerada
typestring
PREVIEW com dryRun
Valores aceitos:CYCLE_SKIPPEDPREVIEW
subscriptionIdstring
ID da assinatura
cycleNumbernumber
Ciclo que seria pulado
chargeDatestring
Data da cobrança do ciclo
amountnumber
Valor do ciclo, em reais
chargesToCancelarray[1]
Cobranças em aberto que seriam canceladas
movedAdjustmentsnumber
Ajustes de pró-rata que passariam para o próximo ciclo
nextCycleobject
Próximo ciclo
400sem motivo▾
JSON
{
    "error": {
        "message": "Informe o motivo para pular a cobrança",
        "code": "INVALID_DATA",
        "details": [
            {
                "code": "custom",
                "path": ["reason"],
                "message": "Informe o motivo para pular a cobrança"
            }
        ],
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
400ciclo não pode ser pulado▾
JSON
{
    "error": {
        "message": "O ciclo 3 está PAID e não pode ser pulado",
        "code": "CYCLE_NOT_SKIPPABLE",
        "details": null,
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
400ciclo com cobrança paga▾
JSON
{
    "error": {
        "message": "O ciclo já tem cobrança paga e não pode ser pulado",
        "code": "CYCLE_PARTIALLY_PAID",
        "details": null,
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
400Pix Automático▾
JSON
{
    "error": {
        "message": "Ciclos de Pix Automático não podem ser pulados",
        "code": "PIX_AUTOMATICO_NOT_SKIPPABLE",
        "details": null,
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
400assinatura não ativada▾
JSON
{
    "error": {
        "message": "Assinatura ainda não ativada; para dar dias grátis no início use o período de teste",
        "code": "SUBSCRIPTION_NOT_ACTIVATED",
        "details": null,
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
400boleto não cancelado▾
JSON
{
    "error": {
        "message": "O banco recusou o cancelamento do boleto cha_xxx (ele pode já ter sido pago e estar compensando). O ciclo não foi pulado.",
        "code": "CHARGE_CANCEL_REJECTED",
        "details": { "failedChargeId": "cha_xxx", "canceledCharges": [] },
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
404ciclo não encontrado▾
JSON
{
    "error": {
        "message": "Ciclo não encontrado",
        "code": "CYCLE_NOT_FOUND",
        "details": null,
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}

← Anterior

Aplicar desconto em uma cobrança

Próximo →

Atualizar configurações