Cancelar uma 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 '{ "reason": "Cliente solicitou cancelamento", "immediately": false }'

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`reason`	string	Não	Motivo do cancelamento (máx. 255)
`immediately`	boolean	Não	`true` cancela na hora (status → `canceled`, ciclos abertos cancelados); ausente/`false` cancela no fim do período (mantém o status atual e desliga a renovação)

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: é esse campo que diz que nenhum novo ciclo será agendado. 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": "[email protected]" },
  "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",
  "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 }
}

A confirmação de cancelamento dispara o webhook subscription.canceled.

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

`error.code`	HTTP	Quando
`subscriptionNotFound`	404	Assinatura inexistente
`subscriptionAlreadyCanceled`	422	A assinatura já está cancelada