Skip to main content

​
Pausar

PATCH /api/v1/subscriptions/{uuid}/pause — requer X-Client-ID + X-API-Key. 
{
  "paused_until": "2026-09-01"
}
paused_until é opcional. Se informado, a assinatura retoma automaticamente nessa data via cron. Caso contrário, permanece pausada até um resume explícito. Apenas assinaturas em active ou trialing podem ser pausadas.

​
Retomar

PATCH /api/v1/subscriptions/{uuid}/resume — requer X-Client-ID + X-API-Key. Corpo vazio. Recalcula next_billing_at a partir da data atual, respeitando o billing_day.

​
Cancelar

DELETE /api/v1/subscriptions/{uuid} — requer X-Client-ID + X-API-Key. 
{
  "at_period_end": true
}
at_period_endComportamento
false (padrão)Cancela imediatamente — sem cobrança do período em andamento
trueAgenda para o fim do período atual — cliente mantém acesso até lá
Quando at_period_end: true, a assinatura continua active mas exibe cancel_at_period_end: true e cancel_at com a data de expiração. O cancelamento é executado automaticamente pelo cron.

​
Trocar plano

PATCH /api/v1/subscriptions/{uuid}/plan — requer X-Client-ID + X-API-Key. 
{
  "new_plan_uuid": "018f9z8y-7x6w-5v4u-3t2s-1r0q9p8o7n6m",
  "immediately": false
}
immediatelyComportamento
false (padrão)Troca agendada para o início do próximo período
trueTroca imediata com pro-rata: crédito proporcional ao tempo não utilizado no período atual é calculado e descontado do novo valor
A troca é classificada automaticamente como upgrade (novo valor ≥ atual) ou downgrade (novo valor < atual) e sinalizada no webhook.

​
Atualizar cartão

PATCH /api/v1/subscriptions/{uuid}/card — requer X-Client-ID + X-API-Key. 
{
  "card_token": "card_novocartao..."
}
Use quando o cartão anterior for recusado (estado past_due) ou quando o cliente adicionar um novo método de pagamento. O cartão deve pertencer ao mesmo cliente da assinatura.
Após atualizar o cartão de uma assinatura past_due, chame Antecipar para tentar cobrar imediatamente sem esperar o próximo ciclo automático.

​
Antecipar

POST /api/v1/subscriptions/{uuid}/anticipate — requer X-Client-ID + X-API-Key. Corpo vazio. Cobra o próximo ciclo agora, independentemente de next_billing_at. Ideal para:
  • Reativar assinaturas past_due após atualização de cartão
  • Testes de integração
  • Cobranças sob demanda antecipadas pelo operador
Retorna o ciclo criado com o resultado da tentativa de cobrança.

​
Aplicar cupom

POST /api/v1/subscriptions/{uuid}/coupon — requer X-Client-ID + X-API-Key. 
{
  "coupon_code": "RETENCAO10"
}
Substitui o cupom atual (se houver). O desconto passa a valer a partir do próximo ciclo. O contador de max_cycles é resetado — os N ciclos com desconto são contados do zero.