Encerrar

Cancelar assinatura

Cancela a assinatura.

DELETE/v1/subscriptions/:subscriptionId

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

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

Quando o cancelamento vale:

Com período já pago pela frente: o cancelamento fica agendado para o fim desse período (cancelAtPeriodEnd: true). O cliente continua com acesso até lá e não há novas cobranças. Dá para desfazer com Desfazer cancelamento agendado.
Sem período pago (nunca pagou, venda avulsa ou período já encerrado): cancela na hora. Cobranças em aberto são canceladas.

Use Ver uma assinatura e o campo cancellation para saber, antes, qual dos dois vai acontecer.

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

{
    "reason": "Cliente pediu o cancelamento" 
}

Schema

reasonstringopcional

Motivo, gravado no histórico

← Anterior

Atualizar configurações

Desfazer cancelamento agendado

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

const options = {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200cancelamento agendado▾

JSON

{
    "success": true, 
    "message": "Cancelamento agendado para o fim do período vigente", 
    "subscriptionId": "sub_xxx", 
    "status": "ACTIVE", 
    "cancelAtPeriodEnd": true, 
    "immediate": false, 
    "effectiveAt": "2026-11-10T00:00:00.000Z", 
    "reason": "Cliente pediu o cancelamento" 
}

Campos da resposta

successboolean

true quando o pedido foi registrado

messagestring

Resultado, em texto

subscriptionIdstring

ID da assinatura

statusstring

Situação atual; muda para CANCELED no fim do período

cancelAtPeriodEndboolean

true: o cancelamento acontece no fim do período pago

immediateboolean

false: cancelamento agendado

effectiveAtstring

Quando a assinatura será cancelada

reasonstring

Motivo informado

200cancelada na hora▾

JSON

{
    "success": true,
    "message": "Assinatura cancelada com sucesso",
    "subscriptionId": "sub_xxx",
    "status": "CANCELED", 
    "immediate": true, 
    "effectiveAt": null,
    "canceledCycles": 1, 
    "canceledCharges": 1, 
    "canceledNotas": 0, 
    "flaggedNotas": 0, 
    "reason": "Cancelamento solicitado"
}

Campos da resposta

successboolean

messagestring

subscriptionIdstring

statusstring

Assinatura cancelada

immediateboolean

true: cancelada agora

effectiveAtobject

canceledCyclesnumber

Ciclos em aberto que foram cancelados

canceledChargesnumber

Cobranças em aberto que foram canceladas

canceledNotasnumber

Notas fiscais canceladas

flaggedNotasnumber

Notas fiscais que precisam de cancelamento manual

reasonstring

400já cancelada▾

JSON

{
    "error": {
        "message": "Assinatura já está cancelada",
        "code": "SUBSCRIPTION_ALREADY_CANCELED",
        "details": null,
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Atualizar configurações

Desfazer cancelamento agendado