Assinaturas

Uma subscription representa o acordo recorrente entre você e um customer. Ela não é só uma cobrança repetida: é a máquina de estado que decide o que será cobrado, quando será cobrado, como o cliente paga, o que acontece durante trial, como updates geram pró-rata e quando a assinatura deve pausar, recuperar ou cancelar. Use subscriptions quando existe uma relação contínua: SaaS mensal, plano anual, clube de assinatura, contrato com add-ons, assentos por usuário, cobrança por consumo ou migração de assinaturas já ativas de outro sistema. Para uma compra avulsa, prefira checkout sessions, payment links ou payment intents. A subscription é a fonte de verdade para acesso e cobrança recorrente. Os campos status, current_period_start, current_period_end, next_billing_at, trial_end, default_payment_method, latest_invoice e items.data[] dizem se o cliente pode usar o produto agora, quando será a próxima tentativa de cobrança e qual valor compõe o ciclo.

Como ela nasce

Cenário	O que acontece
Sem trial, com `default_payment_method`	A Chargefy cria a primeira invoice e, por padrão, tenta cobrar no mesmo request. Pagamento aprovado retorna a subscription `active`; pagamento recusado retorna `incomplete` ou `402`, conforme `payment_behavior`.
Sem trial, sem cartão	A subscription nasce `incomplete`, com invoice aberta. Se a primeira invoice não for paga dentro da janela inicial, vira `incomplete_expired`.
Com trial e cartão salvo	A subscription nasce `trialing`; a primeira cobrança real acontece em `trial_end`.
Com trial e sem cartão	A resposta traz `pending_setup_intent`. Use esse setup intent para coletar/tokenizar um cartão reutilizável antes do fim do trial.
`collection_method: "send_invoice"`	A cada ciclo, a invoice é enviada ou disponibilizada para pagamento manual. Não exige cartão salvo.
Importada com `backdate_start_date`	A subscription preserva o período atual e não cobra de novo o ciclo que já foi cobrado fora da Chargefy.

No create, payment_behavior define a falha da primeira cobrança: allow_incomplete mantém a subscription incomplete para recuperação, default_incomplete não tenta cobrar imediatamente e error_if_incomplete retorna 402 sem criar o recurso público. Esse campo não aparece no objeto retornado porque controla apenas a execução do request.

Cartão, setup intent e tokenização

default_payment_method aponta para um pm_* já salvo. Ele é usado nas cobranças automáticas da primeira invoice, das renovações e de invoices de update quando houver valor a cobrar. Quando uma subscription em trial é criada sem cartão, pending_setup_intent aponta para um seti_*. Esse setup intent existe para coletar um método de pagamento reutilizável sem criar uma cobrança naquele momento. Ao confirmar o setup intent no fluxo seguro, o cartão tokenizado vira o default_payment_method da subscription e pending_setup_intent volta para null. O seu backend nunca precisa guardar dados brutos do cartão. Trabalhe com setup intents, payment methods e os IDs públicos retornados pela Chargefy.

Pró-rata e mudanças de plano

Quando você altera items, troca price, muda quantity, adiciona um add-on ou remove um item, a assinatura pode precisar ajustar o valor proporcional do ciclo atual. Esse ajuste é o pró-rata. Antes de aplicar a mudança, use Invoice Previews para mostrar ao cliente o impacto: crédito por tempo não usado, débito pelo novo plano, saldo aplicado e valor que será cobrado agora ou na próxima invoice. Depois, no update da subscription, proration_behavior e payment_behavior definem se a alteração aplica imediatamente, gera invoice agora, fica em pending_update ou é recusada se não puder cobrar.

Objeto subscription

Este é o formato completo retornado em create, get, update, delete, itens de list e em data.object dos webhooks subscription.*.

{
  "id": "sub_39XMHwCmWucGLctS",
  "object": "subscription",
  "billing_cycle_anchor": "2026-05-19T18:00:00Z",
  "cancel_at": "2026-06-19T18:00:00Z",
  "cancel_at_period_end": true,
  "canceled_at": "2026-05-25T12:00:00Z",
  "cancellation_details": {
    "comment": "Cliente solicitou cancelamento ao fim do ciclo atual.",
    "feedback": "too_expensive",
    "reason": "cancellation_requested"
  },
  "collection_method": "charge_automatically",
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "current_period_end": "2026-06-19T18:00:00Z",
  "current_period_start": "2026-05-19T18:00:00Z",
  "customer": "cus_KUsE9DQgdhy4GvE6",
  "days_until_due": null,
  "default_payment_method": "pm_wGQY5rGNcyoyK261",
  "discount": "disc_QdqC3ua7VGU5nHEw",
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [
      {
        "id": "si_CLrXDUEtZCzTPJq3",
        "object": "subscription_item",
        "aggregate_usage": "sum",
        "amount_discount": 0,
        "amount_subtotal": 9900,
        "amount_tax": 0,
        "amount_total": 9900,
        "created_at": "2026-05-19T18:00:00Z",
        "currency": "brl",
        "discount": "disc_QdqC3ua7VGU5nHEw",
        "metadata": {},
        "position": 0,
        "price": "price_msYPbJb4HUWesx9E",
        "price_data": null,
        "product": "prod_D4ChJnVrwGns67in",
        "quantity": 1,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "subscription": "sub_39XMHwCmWucGLctS",
        "unit_amount": 9900,
        "updated_at": "2026-05-25T12:00:00Z",
        "usage_period_end": "2026-06-19T18:00:00Z",
        "usage_period_start": "2026-05-19T18:00:00Z",
        "usage_type": "metered"
      }
    ],
    "has_more": false,
    "url": "/v1/subscription-items?subscription=sub_39XMHwCmWucGLctS"
  },
  "latest_invoice": "inv_VcFmrCdf9Q9Nve43",
  "livemode": true,
  "metadata": {},
  "next_billing_at": "2026-06-19T18:00:00Z",
  "pause_collection": null,
  "payment_settings": {},
  "pending_setup_intent": null,
  "pending_update": null,
  "resumed_at": null,
  "schedule": "subsched_XZmBV8r1yLcnnKT7",
  "schedule_phase_index": 0,
  "start_date": "2026-05-19T18:00:00Z",
  "status": "active",
  "trial_end": "2026-05-19T18:00:00Z",
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": "2026-05-05T18:00:00Z",
  "updated_at": "2026-05-19T18:00:00Z"
}

string

Identificador da subscription. Usa o prefixo sub_*.

string

Sempre "subscription".

string

Data que ancora os ciclos de cobrança em ISO 8601. As renovações acontecem sempre no “aniversário” dessa data — âncora no dia 19, por exemplo, renova ciclos mensais todo dia 19. Definida na criação (ou na importação) e redefinida quando você reinicia o ciclo com billing_cycle_anchor: "now" no update ou no resume.

string | null

Data em que a subscription termina, em ISO 8601. Vem null quando não há término definido.É um campo declarável: envie cancel_at no create ou no update para vender com prazo — um plano anual entregue como um ano, um contrato com vigência. Na data, a subscription encerra sozinha, sem nenhuma ação posterior.Também vem preenchida quando o término foi declarado por cancel_at_period_end, caso em que reflete o fim do período atual. Os dois caminhos escrevem esta mesma data; o que muda é como o término foi expresso.Término no meio de um período já pago credita o tempo não usado no saldo do cliente, conforme proration_behavior. Término no fim do período não gera crédito — não sobrou tempo a devolver.

boolean

true quando a subscription está marcada para encerrar no fim do período atual; false caso contrário.

string | null

Data em que o cancelamento foi solicitado ou concluído em ISO 8601. Vem null enquanto a subscription não foi cancelada.Prazo declarado por cancel_at não preenche este campo: uma subscription que termina na data combinada cumpriu o contrato, não foi cancelada.

object

Contexto do cancelamento. Os campos vêm null quando não há cancelamento.

Show Campos de cancellation_details

string | null

Comentário livre informado no cancelamento.

string | null

Motivo escolhido pelo cliente no cancelamento.

customer_service — insatisfação com o atendimento.
low_quality — qualidade abaixo do esperado.
missing_features — faltaram recursos de que ele precisava.
other — outro motivo, geralmente detalhado em comment.
switched_service — trocou por outro serviço.
too_complex — achou complexo demais de usar.
too_expensive — achou caro demais.
unused — não estava usando.

string | null

Motivo definido pela Chargefy — não pode ser enviado no request.

cancellation_requested — cancelamento solicitado por você via API ou admin (imediato ou agendado para o fim do período).
canceled_by_retention_policy — cancelada automaticamente por política da assinatura, como um trial que terminou sem payment method com end_behavior: "cancel".
payment_disputed — cancelada após uma disputa de pagamento.
payment_failed — cancelada após falha definitiva de cobrança.

string

Forma de cobrança. charge_automatically (padrão): cada ciclo é cobrado automaticamente no método de pagamento padrão. send_invoice: a cada ciclo a Chargefy envia um link de pagamento (PIX ou boleto) e a fatura é cobrada manualmente — não há cartão arquivado. Quando um cartão é definido como padrão, a assinatura passa automaticamente para charge_automatically.

string

Data de criação em ISO 8601.

string

Moeda da subscription em código ISO de 3 letras minúsculas, como brl.

string

Fim do período de cobrança atual em ISO 8601. É também quando a próxima renovação ocorre.

string

Início do período de cobrança atual em ISO 8601.

string

ID do customer dono da subscription (cus_*).

integer | null

Número de dias até o vencimento das faturas criadas com collection_method: "send_invoice". Vem null quando não foi definido.

string | null

Payment method usado nas cobranças automáticas (pm_*). Vem null quando nenhum método padrão foi definido.

string | null

Desconto aplicado à subscription nas invoices recorrentes.

string | null

Data em que a subscription chegou a um estado final. Vem null enquanto a assinatura ainda pode renovar ou ser recuperada.

object

Lista dos itens recorrentes da subscription, no formato de lista padrão.

Show Campos de items

string

Sempre "list".

array

Array de subscription_item.

Show Campos de subscription_item

string

Identificador do item. Usa o prefixo si_*.

string

Sempre "subscription_item".

string

ID da subscription dona do item (sub_*).

integer

Posição do item na subscription, começando em 0.

string | null

ID do produto do catálogo (prod_*). Vem null quando o item usa um preço definido na hora.

string | null

ID do preço do catálogo (price_*). Vem null quando o item usa price_data.

object | null

Preço definido na criação do item, em vez de um price do catálogo. Vem null quando o item aponta para um price.

string | null

Desconto (disc_*) aplicado somente a este item nas invoices recorrentes. Vem null quando o item não tem desconto próprio.

integer

Quantidade cobrada do item.

string

Moeda do item em código ISO de 3 letras minúsculas.

integer

Valor unitário em centavos.

integer

Subtotal do item em centavos (unit_amount × quantity).

integer

Desconto aplicado ao item em centavos.

integer

Imposto aplicado ao item em centavos.

integer

Total do item em centavos (amount_subtotal − amount_discount + amount_tax).

object | null

Intervalo de recorrência do item. Vem null quando o item não é recorrente.

Show Campos de recurring

string

Unidade do ciclo: day, week, month ou year.

integer

Quantidade de interval por ciclo. Por exemplo, interval: "month" com interval_count: 3 renova a cada 3 meses.

string

Como o item é cobrado. licensed cobra a quantity fixa em todo ciclo. metered cobra pelo uso registrado no período via usage records — a quantidade é apurada no fechamento do ciclo.

string

Para item metered, como os usage records do período são agregados na cobrança.

sum — soma todos os registros do período.
last_during_period — usa o último registro feito dentro do período.
last_ever — usa o último registro já feito, mesmo que seja de um período anterior.
max — usa o maior registro do período.

string | null

Início do período de apuração de uso atual, para item metered. Vem null em item licensed.

string | null

Fim do período de apuração de uso atual, para item metered. Vem null em item licensed.

object

Objeto livre do item. Quando vazio, retorna {}.

string

Data de criação do item em ISO 8601.

string | null

Data da última atualização do item em ISO 8601. Vem null enquanto o item nunca foi atualizado.

boolean

Indica se há mais itens além dos retornados.

string

URL relativa dos itens desta subscription.

string | null

Invoice mais recente da subscription. Vem null antes da primeira invoice.

boolean

true em produção; false em ambiente de teste.

object

Objeto livre para correlacionar a subscription com o seu sistema. Quando vazio, retorna {}.

string

Momento da próxima cobrança de ciclo em ISO 8601. Acompanha current_period_end: é a data da renovação, e avança junto com o período a cada ciclo cobrado.

object | null

Configuração para pausar a cobrança de faturas mantendo a subscription no status atual. Vem null quando a cobrança não está pausada.Durante a pausa o ciclo continua avançando e a invoice de cada ciclo continua sendo criada — o que muda é apenas o destino dessa invoice, definido por behavior.

Show Campos de pause_collection

string

O que acontece com as invoices geradas enquanto a cobrança está pausada.

keep_as_draft — a invoice fica como rascunho, sem cobrança. Pode ser finalizada e cobrada depois, preservando o valor do período pausado.
mark_uncollectible — a invoice é marcada como incobrável; o valor do período pausado é abandonado.
void — a invoice é anulada; o período pausado não gera cobrança.

string | null

Data em que a cobrança volta automaticamente, em ISO 8601. Vem null quando a pausa não tem prazo — nesse caso a retomada é manual, enviando pause_collection: null no update.

object

Configurações de pagamento aplicadas às faturas criadas pela subscription. Hoje não há configurações disponíveis e o campo retorna {}; ele existe no contrato para receber opções futuras sem quebrar integrações.

string | null

Setup intent pendente para coletar ou confirmar método de pagamento reutilizável. Em trials criados sem default_payment_method, a Chargefy cria esse setup intent automaticamente; ao confirmá-lo, o método salvo vira o default_payment_method da subscription e este campo volta para null.

object | null

Atualização pendente criada por um update com payment_behavior: "pending_if_incomplete". A alteração fica retida até a invoice de update ser paga; se não for paga até expires_at, a atualização é descartada e o campo volta para null, sem mudar a assinatura.

Show Campos de pending_update

string

Prazo para o pagamento da invoice de update em ISO 8601 — até 23 horas após o update, ou antes, se o trial ou o período atual terminar primeiro.

string

Invoice (inv_*) que precisa ser paga para a alteração ser aplicada.

array

Como os itens da assinatura ficarão depois que a atualização for aplicada. Cada entrada carrega apenas id, metadata, price, price_data e quantity — não é o objeto subscription_item completo.

string | null

Data da última retomada de uma subscription pausada. Vem null quando nunca foi retomada.

string | null

Subscription schedule (subsched_*) que controla mudanças programadas de fase desta assinatura. Vem null quando a assinatura não é gerenciada por uma schedule.

integer | null

Índice da fase atual dentro da schedule associada, começando em 0. Vem null quando não há schedule.

string

Data de início da subscription em ISO 8601.

string

Estado atual da subscription.

Show Valores de status

string

Criada sem trial e aguardando o pagamento da primeira invoice. A assinatura ainda não está valendo; se a primeira cobrança não for paga em até 23 horas, vira incomplete_expired.

string

A primeira invoice não foi paga dentro da janela inicial. Estado terminal: a invoice aberta é anulada e nenhuma nova invoice é gerada.

string

Em período de teste. A primeira cobrança real acontece em trial_end. O que ocorre se o trial terminar sem payment method é controlado por trial_settings.end_behavior.missing_payment_method.

string

Em dia. As renovações são cobradas a cada ciclo, na data indicada em next_billing_at.

string

A cobrança do ciclo falhou ou ainda precisa de ação. A Chargefy segue retentando automaticamente; se todas as retentativas se esgotarem, a subscription vira unpaid.

string

As retentativas automáticas se esgotaram. As invoices continuam abertas e cobráveis manualmente — troque o default_payment_method e retente, ou envie o link de pagamento da invoice —, mas nenhuma cobrança automática é feita. O pagamento de qualquer invoice aberta reativa a subscription.

string

Cancelada. Estado terminal: não renova nem cobra.

string

O trial terminou sem payment method e trial_settings.end_behavior.missing_payment_method era pause. Nenhuma invoice é gerada até a retomada via /resume. Não confunda com pause_collection, que pausa apenas a cobrança mantendo o status atual.

string | null

Fim do período de trial em ISO 8601 para subscriptions iniciadas em trial. Vem null em subscriptions sem trial.

object

Política aplicada quando o trial termina.

Show Campos de trial_settings

object

Comportamento de fim de trial.

string

Dentro de end_behavior: o que fazer se o trial terminar sem payment method definido. Padrão: create_invoice.

create_invoice (padrão) — gera a invoice do primeiro ciclo mesmo sem método para cobrar; a assinatura pode ficar past_due.
pause — deixa a subscription em paused, sem gerar a invoice do fim do trial, até ser retomada via /resume com um payment method.
cancel — cancela a subscription no fim do trial.

string | null

Início do trial em ISO 8601. Vem null em subscriptions sem trial.

string | null

Data da última atualização em ISO 8601. Vem null enquanto a subscription nunca foi atualizada.

Como ler na prática

Pergunta	Campos principais
O cliente pode acessar o produto agora?	`status`, `trial_end`, `cancel_at`, `ended_at`. Em geral, `trialing` e `active` mantêm acesso; `canceled` e `incomplete_expired` são finais.
Quando será a próxima cobrança?	`next_billing_at`, `current_period_end`, `collection_method`, `pause_collection`.
O cliente está em trial?	`status: "trialing"`, `trial_start`, `trial_end`, `trial_settings`.
Falta coletar cartão?	`default_payment_method: null` junto de `pending_setup_intent` em trial, ou invoice aberta quando a assinatura está `incomplete`/`past_due`.
O plano foi alterado mas ainda depende de pagamento?	`pending_update` preenchido, normalmente com `invoice`, `expires_at` e os itens que serão aplicados após o pagamento.
A subscription tem data para terminar?	`cancel_at` preenchido e `status` ainda não terminal. `cancel_at_period_end: true` indica que o término foi expresso como “não renova depois deste ciclo”.
A cobrança está pausada sem pausar o ciclo?	`pause_collection` preenchido. O status pode continuar `active`; o ciclo segue avançando.
A assinatura cobra por uso?	Algum `items.data[].usage_type` igual a `metered`, com `usage_period_start` e `usage_period_end`.

Cenários comuns

Trial com cartão a coletar

Uma subscription em trial pode começar sem cartão. Nesse caso, ela fica trialing, aponta para um pending_setup_intent e só deve cobrar no fim do trial. Seu produto pode liberar acesso durante o trial e, em paralelo, pedir ao cliente para salvar o cartão antes de trial_end.

{
  "id": "sub_39XMHwCmWucGLctS",
  "object": "subscription",
  "billing_cycle_anchor": "2026-06-02T18:00:00Z",
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null
  },
  "collection_method": "charge_automatically",
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "current_period_end": "2026-06-02T18:00:00Z",
  "current_period_start": "2026-05-19T18:00:00Z",
  "customer": "cus_KUsE9DQgdhy4GvE6",
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [
      {
        "id": "si_CLrXDUEtZCzTPJq3",
        "object": "subscription_item",
        "aggregate_usage": "sum",
        "amount_discount": 0,
        "amount_subtotal": 9900,
        "amount_tax": 0,
        "amount_total": 9900,
        "created_at": "2026-05-19T18:00:00Z",
        "currency": "brl",
        "discount": null,
        "metadata": {},
        "position": 0,
        "price": "price_msYPbJb4HUWesx9E",
        "price_data": null,
        "product": "prod_D4ChJnVrwGns67in",
        "quantity": 1,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "subscription": "sub_39XMHwCmWucGLctS",
        "unit_amount": 9900,
        "updated_at": null,
        "usage_period_end": null,
        "usage_period_start": null,
        "usage_type": "licensed"
      }
    ],
    "has_more": false,
    "url": "/v1/subscription-items?subscription=sub_39XMHwCmWucGLctS"
  },
  "latest_invoice": null,
  "livemode": true,
  "metadata": {},
  "next_billing_at": "2026-06-02T18:00:00Z",
  "pause_collection": null,
  "payment_settings": {},
  "pending_setup_intent": "seti_17BpqwdPsdXTw8Wc",
  "pending_update": null,
  "resumed_at": null,
  "schedule": null,
  "schedule_phase_index": null,
  "start_date": "2026-05-19T18:00:00Z",
  "status": "trialing",
  "trial_end": "2026-06-02T18:00:00Z",
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "pause"
    }
  },
  "trial_start": "2026-05-19T18:00:00Z",
  "updated_at": null
}

Se trial_settings.end_behavior.missing_payment_method for pause, a subscription entra em paused quando o trial termina sem cartão. Se for create_invoice, a primeira invoice é criada mesmo sem método automático. Se for cancel, a assinatura termina no fim do trial.

Upgrade com pró-rata

Ao trocar de plano no meio do ciclo, a Chargefy pode calcular o crédito do plano antigo e o débito do novo plano. Use invoice_preview antes de aplicar a troca. Se o update usar payment_behavior: "pending_if_incomplete", a mudança fica em pending_update até a invoice de update ser paga.

{
  "id": "sub_39XMHwCmWucGLctS",
  "object": "subscription",
  "billing_cycle_anchor": "2026-05-19T18:00:00Z",
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null
  },
  "collection_method": "charge_automatically",
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "current_period_end": "2026-06-19T18:00:00Z",
  "current_period_start": "2026-05-19T18:00:00Z",
  "customer": "cus_KUsE9DQgdhy4GvE6",
  "days_until_due": null,
  "default_payment_method": "pm_wGQY5rGNcyoyK261",
  "discount": null,
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [
      {
        "id": "si_CLrXDUEtZCzTPJq3",
        "object": "subscription_item",
        "aggregate_usage": "sum",
        "amount_discount": 0,
        "amount_subtotal": 9900,
        "amount_tax": 0,
        "amount_total": 9900,
        "created_at": "2026-05-19T18:00:00Z",
        "currency": "brl",
        "discount": null,
        "metadata": {},
        "position": 0,
        "price": "price_msYPbJb4HUWesx9E",
        "price_data": null,
        "product": "prod_D4ChJnVrwGns67in",
        "quantity": 1,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "subscription": "sub_39XMHwCmWucGLctS",
        "unit_amount": 9900,
        "updated_at": null,
        "usage_period_end": null,
        "usage_period_start": null,
        "usage_type": "licensed"
      }
    ],
    "has_more": false,
    "url": "/v1/subscription-items?subscription=sub_39XMHwCmWucGLctS"
  },
  "latest_invoice": "inv_cBUPgz9vG6gKqSC3",
  "livemode": true,
  "metadata": {},
  "next_billing_at": "2026-06-19T18:00:00Z",
  "pause_collection": null,
  "payment_settings": {},
  "pending_setup_intent": null,
  "pending_update": {
    "expires_at": "2026-05-21T11:00:00Z",
    "invoice": "inv_cBUPgz9vG6gKqSC3",
    "subscription_items": [
      {
        "id": "sub_bHoj8ooYDKkuU8SG",
        "metadata": {},
        "price": "price_qXY69GmbFDiNctMJ",
        "price_data": null,
        "quantity": 3
      }
    ]
  },
  "resumed_at": null,
  "schedule": null,
  "schedule_phase_index": null,
  "start_date": "2026-05-19T18:00:00Z",
  "status": "active",
  "trial_end": null,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": null,
  "updated_at": "2026-05-20T12:00:00Z"
}

Os itens dentro de pending_update.subscription_items descrevem o alvo da atualização e carregam apenas id, metadata, price, price_data e quantity — os itens em items.data[] continuam mostrando o estado atual até a invoice ser paga. Quando a invoice é paga, a alteração é aplicada e o webhook subscription.pending.update.applied é emitido. Se expirar sem pagamento, a alteração é descartada e chega subscription.pending.update.expired.

Uso medido

Itens metered cobram pelo consumo registrado no período. A subscription mostra a janela atual de apuração no item; o consumo em si é enviado por usage records.

{
  "id": "si_CLrXDUEtZCzTPJq3",
  "object": "subscription_item",
  "aggregate_usage": "sum",
  "amount_discount": 0,
  "amount_subtotal": 9900,
  "amount_tax": 0,
  "amount_total": 9900,
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "discount": null,
  "metadata": {},
  "position": 0,
  "price": "price_msYPbJb4HUWesx9E",
  "price_data": null,
  "product": "prod_D4ChJnVrwGns67in",
  "quantity": 1,
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "subscription": "sub_39XMHwCmWucGLctS",
  "unit_amount": 9900,
  "updated_at": null,
  "usage_period_end": "2026-06-19T18:00:00Z",
  "usage_period_start": "2026-05-19T18:00:00Z",
  "usage_type": "metered"
}

No fechamento do ciclo, a Chargefy agrega os usage records conforme aggregate_usage e gera a linha correspondente na invoice.

Cancelamento no fim do período

Quando o cliente deve manter acesso até o fim do ciclo atual, não cancele imediatamente. Use cancel_at_period_end: true. A subscription continua active, mas cancel_at mostra a data de corte.

{
  "id": "sub_39XMHwCmWucGLctS",
  "object": "subscription",
  "billing_cycle_anchor": "2026-05-19T18:00:00Z",
  "cancel_at": "2026-06-19T18:00:00Z",
  "cancel_at_period_end": true,
  "canceled_at": "2026-05-25T12:00:00Z",
  "cancellation_details": {
    "comment": "Cliente solicitou cancelamento ao fim do ciclo atual.",
    "feedback": "too_expensive",
    "reason": "cancellation_requested"
  },
  "collection_method": "charge_automatically",
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "current_period_end": "2026-06-19T18:00:00Z",
  "current_period_start": "2026-05-19T18:00:00Z",
  "customer": "cus_KUsE9DQgdhy4GvE6",
  "days_until_due": null,
  "default_payment_method": "pm_wGQY5rGNcyoyK261",
  "discount": null,
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [
      {
        "id": "si_CLrXDUEtZCzTPJq3",
        "object": "subscription_item",
        "aggregate_usage": "sum",
        "amount_discount": 0,
        "amount_subtotal": 9900,
        "amount_tax": 0,
        "amount_total": 9900,
        "created_at": "2026-05-19T18:00:00Z",
        "currency": "brl",
        "discount": null,
        "metadata": {},
        "position": 0,
        "price": "price_msYPbJb4HUWesx9E",
        "price_data": null,
        "product": "prod_D4ChJnVrwGns67in",
        "quantity": 1,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "subscription": "sub_39XMHwCmWucGLctS",
        "unit_amount": 9900,
        "updated_at": null,
        "usage_period_end": null,
        "usage_period_start": null,
        "usage_type": "licensed"
      }
    ],
    "has_more": false,
    "url": "/v1/subscription-items?subscription=sub_39XMHwCmWucGLctS"
  },
  "latest_invoice": "inv_VcFmrCdf9Q9Nve43",
  "livemode": true,
  "metadata": {},
  "next_billing_at": "2026-06-19T18:00:00Z",
  "pause_collection": null,
  "payment_settings": {},
  "pending_setup_intent": null,
  "pending_update": null,
  "resumed_at": null,
  "schedule": null,
  "schedule_phase_index": null,
  "start_date": "2026-05-19T18:00:00Z",
  "status": "active",
  "trial_end": null,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": null,
  "updated_at": "2026-05-25T12:00:00Z"
}

Para cancelar agora, use DELETE /v1/subscriptions/{id}. A assinatura vira canceled, para de renovar e emite subscription.canceled.

Pausa de cobrança

pause_collection não é a mesma coisa que status: "paused". Pausar cobrança mantém o ciclo avançando e decide o que fazer com as invoices criadas durante a pausa. Já status: "paused" acontece quando um trial termina sem payment method e a política de fim de trial manda pausar a assinatura.

{
  "id": "sub_39XMHwCmWucGLctS",
  "object": "subscription",
  "billing_cycle_anchor": "2026-05-19T18:00:00Z",
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null
  },
  "collection_method": "charge_automatically",
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "current_period_end": "2026-06-19T18:00:00Z",
  "current_period_start": "2026-05-19T18:00:00Z",
  "customer": "cus_KUsE9DQgdhy4GvE6",
  "days_until_due": null,
  "default_payment_method": "pm_wGQY5rGNcyoyK261",
  "discount": null,
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [
      {
        "id": "si_CLrXDUEtZCzTPJq3",
        "object": "subscription_item",
        "aggregate_usage": "sum",
        "amount_discount": 0,
        "amount_subtotal": 9900,
        "amount_tax": 0,
        "amount_total": 9900,
        "created_at": "2026-05-19T18:00:00Z",
        "currency": "brl",
        "discount": null,
        "metadata": {},
        "position": 0,
        "price": "price_msYPbJb4HUWesx9E",
        "price_data": null,
        "product": "prod_D4ChJnVrwGns67in",
        "quantity": 1,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "subscription": "sub_39XMHwCmWucGLctS",
        "unit_amount": 9900,
        "updated_at": null,
        "usage_period_end": null,
        "usage_period_start": null,
        "usage_type": "licensed"
      }
    ],
    "has_more": false,
    "url": "/v1/subscription-items?subscription=sub_39XMHwCmWucGLctS"
  },
  "latest_invoice": "inv_VcFmrCdf9Q9Nve43",
  "livemode": true,
  "metadata": {},
  "next_billing_at": "2026-06-19T18:00:00Z",
  "pause_collection": {
    "behavior": "keep_as_draft",
    "resumes_at": "2026-07-01T00:00:00Z"
  },
  "payment_settings": {},
  "pending_setup_intent": null,
  "pending_update": null,
  "resumed_at": null,
  "schedule": null,
  "schedule_phase_index": null,
  "start_date": "2026-05-19T18:00:00Z",
  "status": "active",
  "trial_end": null,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": null,
  "updated_at": "2026-05-25T12:00:00Z"
}

Como processar no seu sistema

Use subscription.created, subscription.updated, subscription.canceled, subscription.paused e subscription.resumed para atualizar acesso e estado local.
Use eventos de invoice e payment intent para fulfillment financeiro. A subscription diz o contrato e o lifecycle; a invoice diz o que foi cobrado; o payment intent diz se a tentativa de pagamento teve sucesso, falhou ou exige ação.
Para liberar acesso, prefira uma regra explícita por status. trialing e active normalmente liberam acesso; past_due e unpaid dependem da sua política de produto; canceled e incomplete_expired são terminais.
Para mudanças de plano, gere uma invoice preview, mostre o valor ao cliente e só depois aplique o update.
Para trial sem cartão, acompanhe pending_setup_intent e colete o método reutilizável antes de trial_end.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos:

O payload sempre carrega o objeto subscription completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Como ela nasce

Cartão, setup intent e tokenização

Pró-rata e mudanças de plano

Objeto subscription

Como ler na prática

Cenários comuns

Trial com cartão a coletar

Upgrade com pró-rata

Uso medido

Cancelamento no fim do período

Pausa de cobrança

Como processar no seu sistema

Operações

Eventos

​Como ela nasce

​Cartão, setup intent e tokenização

​Pró-rata e mudanças de plano

​Objeto subscription

​Como ler na prática

​Cenários comuns

​Trial com cartão a coletar

​Upgrade com pró-rata

​Uso medido

​Cancelamento no fim do período

​Pausa de cobrança

​Como processar no seu sistema

​Operações

​Eventos

Como ela nasce

Cartão, setup intent e tokenização

Pró-rata e mudanças de plano

Objeto subscription

Como ler na prática

Cenários comuns

Trial com cartão a coletar

Upgrade com pró-rata

Uso medido

Cancelamento no fim do período

Pausa de cobrança

Como processar no seu sistema

Operações

Eventos