Cancelar uma assinatura

Encerra uma assinatura para que ela pare de gerar e cobrar novos ciclos. O cancelamento pode ser imediato ou agendado para o fim do ciclo atual, conforme a política configurada na sua conta; em ambos os casos a assinatura termina em canceled e a Selectwin emite o webhook subscription.canceled.

DELETE /v1/subscriptions/{subscriptionId}

Como funciona

"Cancelar" aqui significa encerrar a recorrência, não apagar o registro. A assinatura continua existindo (você ainda consegue lê-la pelo Read e ver seu histórico de Ciclos); o que muda é que ela não produz mais cobranças futuras.

O que o servidor faz ao receber a chamada:

1. Marca a assinatura como canceled e interrompe o agendamento de ciclos futuros.
2. Encerra o ciclo em aberto. Dependendo da política de cancelamento da conta, isso ocorre de duas formas:
   • Imediato — o currentCycle em aberto também vai para canceled e nenhuma cobrança pendente é executada.
   • Ao fim do ciclo — a assinatura permanece valendo até o vencimento do ciclo atual e só então deixa de renovar.
3. Dispara o webhook subscription.canceled (veja o Overview para o ciclo de estados completo).

Quando usar

• O cliente solicitou o fim da assinatura (cancelamento, churn).
• A cobrança recorrente não deve mais acontecer (produto descontinuado, conta encerrada).

Quando não usar:

• Pausa temporária com intenção de retomar → a API não tem operação de pausa/retomada de assinatura. Avalie ajustar o fluxo no seu sistema ou cancelar e recriar quando o cliente voltar.
• Devolver dinheiro de um ciclo pago → estorne a transação em Transações.
• Antecipar a próxima cobrança sem encerrar → force a renovação do ciclo (POST em Ciclos) — note que isso adianta a cobrança, não a adia.

Requisição

Headers

Não há corpo na requisição. Veja Autenticação e Convenções para os detalhes gerais.

Parâmetros de caminho

Parâmetros de query (opcionais — analytics de churn)

Use estes campos para registrar por que o cliente cancelou. Eles alimentam o painel de churn e são opcionais; não afetam a mecânica do cancelamento.

Exemplo curl

Cancelamento simples:

curl -X DELETE "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Cancelamento com motivo de churn (lembre de codificar o texto na URL):

curl -X DELETE "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc?cancelReasonCategory=tooExpensive&cancelReason=Achei%20caro" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK

A resposta devolve a assinatura cancelada completa (mesmo formato do Read), agora com status: "canceled" e o currentCycle também em canceled quando o cancelamento é imediato. Confirme o sucesso pelo campo status, não apenas pelo código HTTP.

{
  "id": "subs_01hqzvabc",
  "status": "canceled",
  "currency": "BRL",
  "method": "credit",
  "type": "prepaid",
  "currentCycle": {
    "id": "cyc_01hqzvabc",
    "cycle": 3,
    "status": "canceled",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-30T23:59:59.000Z",
    "dueDate": "2026-04-01T00:00:00.000Z",
    "billedAt": null,
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-01T00:00:00.000Z"
  },
  "customer": {
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]"
  },
  "billing": {
    "frequency": "monthly",
    "frequencyCount": 1,
    "freeTrialDays": 0
  },
  "discount": {
    "value": 500,
    "type": "flat",
    "percentageOfAmount": null
  },
  "items": [
    {
      "id": "item_01hqzvabc",
      "quantity": 1,
      "unitPrice": 9900,
      "name": "Premium Plan",
      "currency": "BRL"
    }
  ],
  "externalReference": "SUB-1001",
  "metadata": { "campaign": "launch" },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc",
      "method": "DELETE",
      "description": "Cancel the subscription."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/subscriptions",
      "method": "POST",
      "description": "Create a new subscription."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/subscriptions",
      "method": "GET",
      "description": "List subscriptions."
    }
  }
}

O exemplo acima está resumido. A resposta real traz o objeto inteiro da assinatura (customer, billing, splits, items, callback etc.), idêntico ao do Read. Valores monetários estão em centavos (9900 = R$ 99,00) e datas em ISO 8601 UTC.

Campos-chave para confirmar o cancelamento:

Erros

Trate sempre pelo error.code, nunca pela message (veja Tratamento de Erros e o Catálogo de Códigos de Erro).

Boas práticas

• Confirme pelo status: "canceled" na resposta, não só pelo HTTP 200, antes de marcar o cliente como cancelado no seu sistema.
• Registre o motivo de churn via cancelReason / cancelReasonCategory — é a forma de manter seu painel de cancelamentos confiável e custa apenas dois parâmetros de query.
• Cancelamento é irreversível. Confirme com o cliente antes de cancelar quando houver chance de retomada, pois retomar a cobrança exige criar uma nova assinatura.
• Cancelar é seguro de repetir, mas não idempotente: uma segunda chamada na assinatura já cancelada tende a retornar unprocessableEntity (422). Trate esse caso como "já cancelada", não como falha.
• Reaja ao webhook subscription.canceled em vez de fazer polling — é a fonte de verdade assíncrona da mudança de estado (veja Proibição de Polling).
• Reembolsos são à parte: se o cliente tem direito a devolução de um ciclo já cobrado, estorne a transação correspondente em Transações — o cancelamento não devolve dinheiro.

Veja também

• Overview — modelo do objeto e ciclo de estados da assinatura.
• Create — criar uma nova assinatura (única forma de "reativar").
• Read — consultar a assinatura e confirmar o status.
• Cycles — listar, consultar e renovar (antecipar) os ciclos de cobrança da assinatura.
• Items e Splits — itens e divisão de recebíveis da assinatura.
• Refund de Transações — estornar um ciclo já cobrado.