Cancelar assinatura
Cancele uma assinatura pela API e saiba, pelo meio de pagamento e pelo status, quando o cancelamento vale.
Use este guia para encerrar a assinatura de um cliente. Depois do cancelamento, o cliente não é mais cobrado.
O momento em que o cancelamento vale depende do meio de pagamento e do status da assinatura. Veja O que acontece em cada caso.
Visão geral
O diagrama mostra o que acontece em cada caso depois do pedido.
Antes de começar
- Um token de acesso. Veja Autenticação; os exemplos assumem a variável
accessToken. - O
idda assinatura, um uuid. Ele vem em:data.idda resposta dePOST /plans/offer/{id}/subscribe;data.subscription.iddos eventosSUBSCRIPTION_*;GET /subscriptions, que lista as assinaturas da sua conta.
Assinaturas do checkout também
A rota cancela qualquer assinatura da sua conta, inclusive as vendidas no checkout da PagPolar em PIX ou boleto.
Passo a passo
Confira o meio de pagamento e o status
O resultado do cancelamento depende de payment_method e de status. Consulte os dois em GET /subscriptions/{id} e compare com O que acontece em cada caso.
Peça o cancelamento
Chame DELETE /subscriptions/{id}. A rota não tem corpo e não usa Idempotency-Key.
curl -X DELETE "https://api.pagpolar.com/v1/subscriptions/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b" \
-H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"const response = await fetch(
'https://api.pagpolar.com/v1/subscriptions/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b',
{
method: 'DELETE',
headers: { Authorization: `Bearer ${accessToken}` },
},
);
console.log(response.status, await response.json());Resposta 200:
{
"data": {
"success": true
}
}Contrato completo: DELETE /subscriptions/{id}.
success: true não quer dizer cancelada
A resposta é sempre 200 com success: true, tenha a assinatura mudado ou não. Quando o status não aceita cancelamento, como um cartão em DRAFT ou PROCESSING, nada muda, e repetir o pedido também não muda nada. Espere a assinatura ficar ACTIVE e peça de novo. Confirme o resultado no próximo passo.
Confirme o resultado
Você confirma pelo webhook ou pela consulta.
Pelo webhook. Quando o cancelamento é efetivado, a sua URL recebe SUBSCRIPTION_CANCELED. Exemplo (resumido):
{
"id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
"event": "SUBSCRIPTION_CANCELED",
"creation_date": "2026-09-20T13:00:05.000Z",
"version": "1.0.0",
"data": {
"subscription": {
"id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
"status": "CANCELED",
"payment_method": "CREDIT_CARD"
},
"source": {
"channel": "API",
"api_credential_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
}
}Pela consulta. Chame GET /subscriptions/{id}:
status | O que significa | O que fazer |
|---|---|---|
CANCELING | Cartão: o pedido foi enviado ao gateway, que ainda não confirmou. | Espere o SUBSCRIPTION_CANCELED. |
CANCELED | O cancelamento foi efetivado. | Encerre a assinatura no seu sistema e revogue o acesso. |
| Igual ao do passo 1 | O status não aceitava cancelamento. Nada mudou. | Veja O que acontece em cada caso. |
Depois do cancelamento efetivado, a consulta mostra:
| Campo | PIX ou boleto | Cartão de crédito |
|---|---|---|
canceled_at | Data e hora do pedido. | Data e hora em que a PagPolar recebeu a confirmação do gateway. |
end_at | Data e hora do pedido. | A data de próxima cobrança informada pelo gateway na confirmação. |
next_billing_at | null | null |
Confira end_at pela consulta
No cartão, canceled_at e end_at são gravados logo depois de o SUBSCRIPTION_CANCELED ser disparado. O evento pode chegar com esses campos ainda vazios. Para decidir até quando manter o acesso, use GET /subscriptions/{id}.
O que acontece em cada caso
| Meio de pagamento | Status no pedido | Status logo depois | Status final | Evento |
|---|---|---|---|---|
| PIX ou boleto | ACTIVE, PENDING_PAYMENT ou PENDING_RENEWAL | CANCELED | CANCELED | SUBSCRIPTION_CANCELED na hora |
| PIX ou boleto | Qualquer outro | Não muda | Não muda | Nenhum |
| Cartão de crédito | ACTIVE | CANCELING | CANCELED, quando o gateway confirma | SUBSCRIPTION_CANCELED na confirmação |
| Cartão de crédito | Qualquer outro, como DRAFT, PROCESSING ou CANCELING | Não muda | Não muda | Nenhum |
Qualquer meio de pagamento que não seja PIX ou boleto segue as regras do cartão.
Reembolso e chargeback também cancelam
A PagPolar também pede o cancelamento da assinatura, sem você chamar a API, nestes casos:
- o cliente pede reembolso total de uma venda da assinatura;
- um pedido de reembolso de uma venda da assinatura é aceito, seja total ou parcial, inclusive o aberto pelo vendedor;
- uma venda da assinatura é estornada;
- o chargeback de uma venda da assinatura é aprovado.
O pedido segue as mesmas regras desta página. Veja O que acontece em cada caso.
Eventos de webhook deste fluxo
| Evento | Quando é enviado | O que fazer |
|---|---|---|
SUBSCRIPTION_CANCELED | Quando o cancelamento é efetivado. Veja O que acontece em cada caso. | Encerre a assinatura e revogue o acesso. |
Para descartar repetidos, use a chave event + data.subscription.id. Veja Processar eventos sem duplicar.
Quando algo dá errado
Além dos erros comuns a todas as rotas, este fluxo pode responder:
| Passo | Situação | Resposta | Como resolver |
|---|---|---|---|
| 1 e 2 | O id não é um uuid. Por exemplo, o código de uma venda. | 400 invalid_request | Envie o id da assinatura. |
| 1 e 2 | Assinatura inexistente ou de outra conta. | 404 com Assinatura não encontrada | Confira o id. |
| 2 | Cartão em ACTIVE e o gateway não aceitou o pedido. | 400 com a mensagem do gateway, ou 500 internal_error | O status continua ACTIVE. Consulte a assinatura e peça de novo mais tarde. Se o erro continuar, fale com o suporte e informe o request_id. |