Agendamentos de assinatura

Uma subscription_schedule agenda mudanças automáticas em uma subscription. Cada fase define itens, cobrança, trial e comportamento de pró-rata para o momento em que ela começa. Use schedules quando você precisa planejar mudanças futuras sem fazer updates manuais no dia da virada: migração de plano, desconto temporário, fase de trial seguida de preço cheio, ou troca programada de itens na assinatura.

Como ler uma schedule

Campo	O que responde
`subscription`	Qual assinatura está sob controle da schedule.
`status`	Se a agenda ainda não começou, está ativa, terminou, foi liberada ou cancelada.
`current_phase`	Janela da fase atual, quando já existe uma fase em vigor.
`current_phase_index`	Posição da fase atual em `phases.data[]`.
`phases.data[]`	Sequência completa de mudanças planejadas.
`end_behavior`	O que acontece com a assinatura depois da última fase: `release` ou `cancel`.

Exemplo de uso

Imagine uma assinatura que começa com um mês promocional e depois segue com o preço cheio. A primeira fase pode apontar para um price promocional ou para um discount; a segunda fase remove o benefício e mantém a assinatura ativa. Com end_behavior: "release", quando a última fase termina, a subscription continua sem novas mudanças programadas pela schedule.

Fases são aplicadas em ordem. Para cancelar ou liberar a agenda antes do fim, use Cancelar schedule ou Liberar schedule.

{
  "id": "subsched_FRG45ukgYP37wiZz",
  "object": "subscription_schedule",
  "canceled_at": null,
  "completed_at": null,
  "created_at": "2026-05-20T12:00:00Z",
  "current_phase": {
    "end_date": "2026-06-20T12:00:00Z",
    "start_date": "2026-05-20T12:00:00Z"
  },
  "current_phase_index": 0,
  "customer": "cus_XEj9zNBDtDU3wBF8",
  "end_behavior": "release",
  "livemode": true,
  "metadata": {},
  "phases": {
    "object": "list",
    "data": [
      {
        "id": "subphase_adDs5wMtaDJK6tR1",
        "object": "subscription_schedule_phase",
        "collection_method": "send_invoice",
        "created_at": "2026-05-20T12:00:00Z",
        "days_until_due": 5,
        "default_payment_method": null,
        "discount": "disc_xbpuN7aPXqModgxU",
        "end_date": "2026-06-20T12:00:00Z",
        "items": [
          {
            "price": "price_8T3AhpVQF8ZGuDBN",
            "quantity": 1
          }
        ],
        "iterations": null,
        "metadata": {},
        "phase_index": 0,
        "proration_behavior": "create_prorations",
        "start_date": "2026-05-20T12:00:00Z",
        "trial_end": "2026-05-27T12:00:00Z",
        "trial_settings": {
          "end_behavior": {
            "missing_payment_method": "create_invoice"
          }
        },
        "updated_at": "2026-05-20T12:05:00Z"
      }
    ],
    "has_more": false,
    "url": "/v1/subscription-schedules/subsched_FRG45ukgYP37wiZz/phases"
  },
  "released_at": null,
  "released_subscription": null,
  "start_date": "2026-05-20T12:00:00Z",
  "status": "active",
  "subscription": "sub_sisHSb62TsURLGMW",
  "updated_at": "2026-05-20T12:05:00Z"
}

string

ID da schedule (subsched_*).

string

O que acontece com a subscription quando a última fase termina.

Valor	Descrição
`release`	Mantém a subscription ativa após a última fase.
`cancel`	Cancela a subscription no fim da última fase.

string

Estado atual da schedule.

Valor	Descrição
`not_started`	Criada, mas a primeira fase ainda não começou.
`active`	Uma fase está em vigor na subscription.
`completed`	Todas as fases terminaram.
`released`	Schedule desvinculada; a subscription segue sem ela.
`canceled`	Schedule cancelada.

object

Lista de fases sequenciais aplicadas à subscription.

Show Campos de cada fase

string | null

Fim da fase. Vem null na última fase de uma schedule sem duração declarada — ela vale até a schedule ser liberada ou cancelada.

integer | null

Duração declarada em número de cobranças, quando a fase foi criada assim em vez de com end_date.Vira null no momento em que a fase começa: a Chargefy converte a contagem na data concreta e a grava em end_date, contando a cadência da assinatura a partir da borda de ciclo real. Os dois campos nunca vêm preenchidos ao mesmo tempo — antes da fase começar há iterations, depois há end_date.

string

Início da fase. Encadeia no fim da fase anterior; quando a anterior foi declarada em iterations, este valor é reajustado na materialização.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Agendamentos de assinatura

Como ler uma schedule

Exemplo de uso

​Como ler uma schedule

​Exemplo de uso

Como ler uma schedule

Exemplo de uso