# Cancelar assinatura URL: https://staging.pagpolar.com/docs/guias/jornadas/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](#o-que-acontece-em-cada-caso). ## Visão geral O diagrama mostra o que acontece em cada caso depois do pedido. ```mermaid sequenceDiagram autonumber participant I as Seu sistema participant A as API PagPolar participant G as Gateway participant W as Seu servidor de webhook I->>A: DELETE /subscriptions/ID alt cartão com status ACTIVE A->>G: pede o cancelamento Note over A: assinatura fica CANCELING A-->>I: 200 com success true G-)A: assinatura cancelada A-)W: SUBSCRIPTION_CANCELED, status CANCELED else PIX ou boleto em ACTIVE, PENDING_PAYMENT ou PENDING_RENEWAL A-)W: SUBSCRIPTION_CANCELED, status CANCELED A-->>I: 200 com success true else qualquer outro caso A-->>I: 200 com success true, nada muda end ``` ## Antes de começar * Um token de acesso. Veja [Autenticação](/docs/guias/fundamentos/autenticacao#obter-o-token); os exemplos assumem a variável `accessToken`. * O `id` da assinatura, um uuid. Ele vem em: * `data.id` da resposta de [`POST /plans/offer/{id}/subscribe`](/docs/referencia/assinaturas/create-subscription); * `data.subscription.id` dos eventos `SUBSCRIPTION_*`; * [`GET /subscriptions`](/docs/referencia/assinaturas/list-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 1. **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}`](/docs/referencia/assinaturas/get-subscription) e compare com [O que acontece em cada caso](#o-que-acontece-em-cada-caso). 2. **Peça o cancelamento** Chame `DELETE /subscriptions/{id}`. A rota não tem corpo e não usa `Idempotency-Key`. #### cURL ```bash curl -X DELETE "https://api.pagpolar.com/v1/subscriptions/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b" \ -H "Authorization: Bearer " ``` #### Node.js ```js 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`: ```json { "data": { "success": true } } ``` Contrato completo: [`DELETE /subscriptions/{id}`](/docs/referencia/assinaturas/cancel-subscription). > **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. 3. **Confirme o resultado** Você confirma pelo webhook ou pela consulta. **Pelo webhook.** Quando o cancelamento é efetivado, a sua URL recebe [`SUBSCRIPTION_CANCELED`](/docs/webhooks/eventos/subscription-canceled). Exemplo (resumido): ```json { "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}`](/docs/referencia/assinaturas/get-subscription): | `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](#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](#o-que-acontece-em-cada-caso). ## Eventos de webhook deste fluxo | Evento | Quando é enviado | O que fazer | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [`SUBSCRIPTION_CANCELED`](/docs/webhooks/eventos/subscription-canceled) | Quando o cancelamento é efetivado. Veja [O que acontece em cada caso](#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](/docs/webhooks/processar-sem-duplicar). ## Quando algo dá errado Além dos [erros comuns a todas as rotas](/docs/guias/fundamentos/erros#erros-comuns), 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`. | ## Próximos passos - [Assinar um plano](/docs/guias/jornadas/assinar-um-plano) — Crie o plano, a oferta de plano e a assinatura no cartão. - [Ciclo de vida da assinatura](/docs/guias/conceitos/ciclo-de-vida-da-assinatura) — Todos os status, no cartão, no PIX e no boleto. - [Processar eventos sem duplicar](/docs/webhooks/processar-sem-duplicar) — Trate repetições e eventos fora de ordem.