# Pular uma cobrança

**Área:** Descontos e cupons

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`

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

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

### Path parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `subscriptionId` | **sim** | ID da assinatura (ex: sub_xxx) - required |
| `cycleNumber` | **sim** | Número do ciclo a pular (ex: 3) - required |

### Request body

```json
{
    "reason": "Mês de brinde", 
    "dryRun": false 
}
```

### Campos do body

**Opcionais**

| Campo | Descrição |
|---|---|
| `reason` | Motivo, gravado no histórico. De 3 a 300 caracteres. Obrigatório sem dryRun |
| `dryRun` | true: só mostra o que vai acontecer, sem pular |

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

| Campo | Descrição |
|---|---|
| `success` | true quando a cobrança foi pulada |
| `type` | CYCLE_SKIPPED, ou PREVIEW com dryRun (valores: CYCLE_SKIPPED, PREVIEW) |
| `subscriptionId` | ID da assinatura |
| `cycleNumber` | Ciclo pulado |
| `skip` | Registro do pulo. Também aparece em billingCycles[].cycle.skip de Ver uma assinatura |
| `skip.skippedAt` | Quando a cobrança foi pulada |
| `skip.skippedBy` | ID de quem pulou |
| `skip.skippedByName` | Nome de quem pulou pelo painel. null quando foi pela API |
| `skip.reason` | Motivo informado |
| `skip.previousStatus` | Situação do ciclo antes do pulo |
| `skip.canceledChargeIds` | Cobranças canceladas |
| `canceledCharges` | Cobranças em aberto que foram canceladas |
| `canceledCharges.chargeId` | ID da cobrança |
| `canceledCharges.invoiceId` | Fatura da cobrança |
| `canceledCharges.paymentType` | Forma de pagamento (valores: PIX, BOLETO, CREDIT_CARD) |
| `canceledCharges.amount` | Valor, em reais |
| `canceledCharges.status` | Situação da cobrança antes do cancelamento |
| `canceledCharges.dueDate` | Vencimento |
| `canceledCharges.nfStatus` | Situação da nota fiscal da cobrança |
| `canceledCharges.notas` | Notas fiscais da cobrança: canceladas, marcadas para revisão, com falha no cancelamento e mantidas |
| `movedAdjustments` | Ajustes de pró-rata que passaram para o próximo ciclo |
| `nextCycle` | Próximo ciclo, já criado |
| `nextCycle.cycleNumber` | Número do próximo ciclo |
| `nextCycle.chargeDate` | Data da próxima cobrança |
| `nextCycle.amount` | Valor previsto, em reais |
| `restoredStatus` | ACTIVE quando a assinatura saiu da inadimplência com o pulo (valores: ACTIVE) |

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

| Campo | Descrição |
|---|---|
| `success` | true quando a prévia foi gerada |
| `type` | PREVIEW com dryRun (valores: CYCLE_SKIPPED, PREVIEW) |
| `subscriptionId` | ID da assinatura |
| `cycleNumber` | Ciclo que seria pulado |
| `chargeDate` | Data da cobrança do ciclo |
| `amount` | Valor do ciclo, em reais |
| `chargesToCancel` | Cobranças em aberto que seriam canceladas |
| `chargesToCancel.chargeId` | ID da cobrança |
| `chargesToCancel.invoiceId` | Fatura da cobrança |
| `chargesToCancel.paymentType` | Forma de pagamento (valores: PIX, BOLETO, CREDIT_CARD) |
| `chargesToCancel.amount` | Valor, em reais |
| `chargesToCancel.status` | Situação atual da cobrança |
| `chargesToCancel.dueDate` | Vencimento |
| `chargesToCancel.nfStatus` | Situação da nota fiscal da cobrança |
| `movedAdjustments` | Ajustes de pró-rata que passariam para o próximo ciclo |
| `nextCycle` | Próximo ciclo |
| `nextCycle.cycleNumber` | Número do próximo ciclo |
| `nextCycle.chargeDate` | Data prevista da próxima cobrança |
| `nextCycle.alreadyExists` | true quando o próximo ciclo já existe e só passa a ser o atual |

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


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


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


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


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


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


### Resposta 404: 404 ciclo não encontrado

```json
{
    "error": {
        "message": "Ciclo não encontrado",
        "code": "CYCLE_NOT_FOUND",
        "details": null,
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
```


---

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