Cancelar assinatura

Cancelar uma assinatura via POST /v1/subscriptions/:id/cancel, imediatamente ou no fim do ciclo pago.

POST /v1/subscriptions/:id/cancel
Authorization: Bearer sk_test_...
Content-Type: application/json

Body

{
  atPeriodEnd?: boolean;   // default false (cancelamento imediato)
}

Valor	Comportamento
`false` (padrão)	Cancela imediatamente. `status` vira `canceled`, `canceledAt` é preenchido.
`true`	Mantém a assinatura ativa até o fim do ciclo pago atual. Enquanto isso, `cancelAtPeriodEnd=true` e o `status` continua `active`. Quando o gateway efetiva o cancelamento no fim do ciclo, a Allya recebe webhook e atualiza para `canceled`. Não suportado por Abacate Pay nem Pagar.me: ver abaixo.

Restrições por gateway

Gateway	`atPeriodEnd=false`	`atPeriodEnd=true`
Abacate Pay	✅	❌: retorna `400 invalid_input`. A API atual da Abacate Pay cancela imediatamente.
Asaas	✅	✅ (usa `endDate` no `nextDueDate`)
Pagar.me	✅	❌: retorna `400 invalid_input`. O Pagar.me v5 não expõe cancelamento agendado nativamente. Cancele imediato (perdendo o resto do ciclo) ou agende manualmente no seu sistema.

Resposta

{
  "id": "sub_4a1c0e7b9d224f5fb8c6102d7e3a9014",
  "status": "canceled",
  "method": "card",
  "gateway": "asaas",
  "amount": 4990,
  "currency": "BRL",
  "interval": "monthly",
  "trialDays": 0,
  "trialEndsAt": null,
  "nextBillingAt": "2026-06-25T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "canceledAt": "2026-05-25T12:34:00.000Z",
  "externalId": "plano-pro-12345",
  "gatewayRef": "gateway_subscription_id",
  "checkoutUrl": "https://checkout.gateway.com/checkout_abc",
  "customer": {
    "name": "Cliente Teste",
    "email": "cliente@example.com",
    "documentLast4": "0000"
  },
  "createdAt": "2026-05-25T12:00:00.000Z"
}

Idempotência

Repetir a chamada de cancelamento é seguro:

Se a assinatura já está canceled, a resposta é 200 com o recurso atual (sem nova chamada ao gateway).
Se a assinatura já tem cancelAtPeriodEnd=true e a nova chamada também pede atPeriodEnd=true, a resposta é 200 com o recurso atual.
Se você chama com atPeriodEnd=false em uma assinatura com cancelAtPeriodEnd=true, o cancelamento é "promovido" para imediato: gateway é chamado.

Erros comuns

HTTP	Erro	Quando
404	`not_found`	A assinatura não existe neste ambiente.
409	`missing_gateway_ref`	Assinatura nunca foi sincronizada com o gateway (criação falhou).
400	`invalid_input` (`atPeriodEnd`)	Combinação não suportada pelo gateway resolvido (ex.: Abacate Pay ou Pagar.me + `atPeriodEnd=true`).
502	`gateway_error`	Falha na chamada ao gateway durante o cancelamento.

Re-assinar

Para cobrar o mesmo cliente de novo após cancelamento, crie uma nova assinatura via POST /v1/subscriptions. Não há reativação de assinatura cancelada.

Veja também

Criar assinatura: para re-assinar.
Status de assinatura: significado de canceled vs cancelAtPeriodEnd=true.
Webhooks: evento subscription.canceled.
Plano obrigatório no Pagar.me: comportamento específico de cancelamento no Pagar.me.