Cancelar Assinatura

POST /v1/subscriptions/{subscriptionId}/cancel

Cancela uma assinatura. Por padrão o cancelamento ocorre no fim do período vigente (o ciclo atual segue válido e nenhum novo ciclo é agendado). Para encerrar imediatamente, envie immediately: true. Retorna a assinatura atualizada. Ciclos já cobrados não são reembolsados automaticamente.

#Requisição

curl -X POST "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cancel" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{ "reasonCode": "switched_provider", "reason": "Cliente encontrou um plano mais barato", "immediately": false }'

#Corpo da requisição

#Motivos (reasonCode)

Um código fora da lista é 400 invalidParameters. O reasonCode é opcional para não quebrar quem já integrava só com o texto, mas recomendamos enviá-lo sempre: é ele que o painel agrupa. O mesmo catálogo vale para o cancelamento que o comprador faz no portal do cliente.

#Resposta 200 OK

Retorna o objeto completo da assinatura (mesma estrutura de Consultar). Com immediately: true, status passa a canceled imediatamente e canceledAt é carimbado.

Como confirmar que o cancelamento pegou. No fim do período o status continua o mesmo de propósito — a assinatura segue valendo até o ciclo pago acabar. O que muda é billing.autoRenew, que vira false, e billing.endDate, que passa a ser o último dia do período pago. O ciclo que estava agendado para o período seguinte é cancelado na hora: nenhuma cobrança sai depois do pedido. No endDate a assinatura vira canceled e o webhook subscription.canceled é enviado. No cancelamento imediato, olhe status e canceledAt.

{
  "id": "subs_01hqzvabc",
  "status": "canceled",
  "method": "credit",
  "type": "recurring",
  "currentCycle": { "id": "scy_01hqzvabc", "cycle": 1, "status": "canceled", "startDate": "2026-04-01T00:00:00.000Z", "endDate": "2026-05-01T00:00:00.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": "joao@example.com" },
  "billing": { "frequency": "monthly", "frequencyCount": 1, "endDate": null, "exactDay": null, "freeTrialDays": null, "autoRenew": false, "address": { "city": "São Paulo", "state": "SP", "country": "BR" } },
  "canceledAt": "2026-04-12T17:56:33.000Z",
  "cancellation": { "reasonCode": "switched_provider", "reason": "Cliente encontrou um plano mais barato", "canceledBy": "seller" },
  "items": [ { "id": "sit_01hqzvabc", "name": "Premium Plan", "enabled": true, "pricingSchema": "recurring", "unitPrice": 9900, "quantity": 1, "currency": "BRL" } ],
  "externalReference": "ORDER-123",
  "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 }
}

O motivo volta em cancellation — na resposta, na consulta e nos webhooks subscription.*: reasonCode (o código da lista), reason (o texto livre) e canceledBy (seller quando foi pela API ou pelo painel, customer quando foi o comprador no portal, platform nos cancelamentos automáticos abaixo). Cancelamentos anteriores à lista continuam com o texto em reason e reasonCode: null.

O cancelamento imediato dispara o webhook subscription.canceled. O cancelamento no fim do período dispara subscription.updated na hora (com autoRenew: false e o endDate) e subscription.canceled quando o período acaba.

#Cancelamentos automáticos

A assinatura também é cancelada na hora, sem chamada sua, quando:

• a cobrança de um ciclo sofre chargeback;
• a cobrança de um ciclo é estornada por inteiro e nenhuma outra cobrança aprovada paga aquele ciclo (estorno parcial não cancela);
• ela nasceu de um checkout com item avulso e o pagamento do item avulso falhou;
• ela nasceu de um checkout só de plano sem trial e a 1ª cobrança, feita no próprio checkout, foi recusada ou o Pix/boleto dela venceu sem pagamento (a compra não aconteceu — a assinatura não vai para pastdue);
• a régua de inadimplência da loja se esgotou: as tentativas de um ciclo acabaram (unpaid) e a carência passou (ver Visão Geral).

Nesses casos cancellation.canceledBy é platform e reasonCode é null.

#Notas

• Para pausar temporariamente em vez de cancelar, use POST /v1/subscriptions/{id}/pause (e POST /v1/subscriptions/{id}/resume para retomar). A assinatura entra em paused e pode voltar a active.
• Reembolsos de transações de ciclos já cobrados são feitos pelo recurso de Transações, individualmente.

#Erros