Skip to main content
Cria uma schedule. Se a primeira fase começa agora, ela é aplicada imediatamente e a próxima fase é agendada. Envie subscription ou customer, nunca os dois (erro 400). Com subscription, a schedule passa a controlar uma assinatura existente. Com customer, ela cria a assinatura a partir de phases[0] — é o caminho de vender com prazo desde a origem, sem precisar criar a assinatura antes só para poder agendá-la em seguida. Para as fases, exatamente um caminho: from_subscription (a fase inicial é gerada sozinha a partir dos itens atuais) ou phases explícitas. Sem nenhum dos dois o request falha com 400; se os dois forem enviados, phases prevalece. Com subscription, ela precisa ter pelo menos um item e não pode estar em estado terminal (canceled ou incomplete_expired — erro 400). Assinatura que já tem uma schedule retorna 409.
​
string
Subscription existente que será controlada pela schedule (sub_*). Obrigatória quando customer não é enviado.
​
string
Customer (cus_*) para quem a assinatura será criada. Obrigatório quando subscription não é enviado.A assinatura nasce de phases[0], pelo mesmo caminho de POST /v1/subscriptions — mesma cobrança inicial, mesmo tratamento de desconto e trial, mesma Idempotency-Key. phases[0].items é obrigatório neste modo: sem assinatura de origem não há itens de onde herdar.Os campos de cobrança de phases[0] (collection_method, days_until_due, default_payment_method, discount, trial_end, trial_settings, metadata) são aplicados à assinatura criada. payment_behavior pode ser enviado na raiz do request.Se a validação das fases recusar depois que a assinatura já nasceu, ela é cancelada e a primeira fatura é anulada antes do erro voltar — você não fica com uma assinatura que não pediu.
​
string | boolean
Atalho que gera a fase inicial sozinho: a fase 0 nasce com os itens atuais da assinatura e termina no fim do período atual. Aceita o próprio ID da subscription (dispensando subscription) ou true junto com subscription.
​
string
Data de início da primeira fase. Aceita ISO 8601, Unix seconds ou now. Padrão: agora.
​
string
O que acontece com a subscription quando a última fase termina. Padrão: release.
​
array
Fases sequenciais e sem sobreposição. Obrigatório quando from_subscription não é enviado; deve ser um array não-vazio.
​
object
Metadata da schedule. Padrão {}.

​
O que a Chargefy resolve sozinha

  • Com customer — a assinatura é criada a partir de phases[0] antes da schedule, e a schedule já nasce apontando para ela. A resposta traz a schedule; o ID da assinatura vem em subscription.
  • Com from_subscription — a fase 0 nasce com os itens atuais da assinatura e end_date no fim do período atual.
  • start_date de cada fase — encadeia no end_date da fase anterior quando não é enviado.
  • items de fase — sem valor explícito, os itens atuais da assinatura.
  • Status inicial — active (com a fase 0 aplicada na hora) quando a primeira fase já começou; senão not_started, com a fase 0 agendada para o start_date.
  • Transições — cada fase seguinte é agendada automaticamente; ao fim da última fase, a Chargefy aplica o end_behavior.
  • iterations → end_date — convertido quando a fase começa, contando a cadência da assinatura um ciclo por vez (o que preserva o comportamento de fim de mês). Se a fase seguinte tinha um início projetado que não bate com o fim real, ele é reajustado junto.
  • Data de término visível — ao entrar na última fase de uma schedule com end_behavior: "cancel", a assinatura recebe cancel_at com a data do encerramento e emite subscription.updated. A data fica disponível durante todo o último ciclo, não apenas quando o encerramento acontece.