Skip to main content
Atualiza uma subscription. A resposta direta retorna o objeto completo atualizado; o diff sai apenas no webhook subscription.updated.
​
string
required
ID da subscription (sub_*).
​
string
Payment method padrão para próximas cobranças (pm_*). Envie null para remover.
​
string
Forma de cobrança dos próximos ciclos.
  • charge_automatically — cada ciclo é cobrado automaticamente no payment method padrão.
  • send_invoice — a cada ciclo a fatura é emitida com um link de pagamento e cobrada manualmente; o vencimento é controlado por days_until_due.
​
integer
Dias até vencimento quando collection_method é send_invoice. O vencimento de cada ciclo é ancorado ao meio-dia UTC do dia alvo — veja Datas, fusos e moedas.
​
string
unchanged para manter o ciclo atual, now para reiniciar o ciclo no momento do update, ou um timestamp ISO 8601 para definir uma âncora específica.
​
string
Ajusta o fim do trial.
  • Timestamp ISO 8601 futuro — estende ou encurta o trial até essa data.
  • now — encerra o trial imediatamente; a cobrança do primeiro ciclo é iniciada na hora.
  • null — remove a data de fim de trial registrada.
​
object
Política aplicada quando o trial termina.
​
string
Desconto aplicado às invoices recorrentes. Envie null para remover.
​
object
Pausa a cobrança das invoices sem mudar o status da subscription — o ciclo continua avançando e a invoice de cada ciclo continua sendo criada; o behavior define o destino dela. Envie null para retomar a cobrança.
​
boolean
Quando true, agenda o encerramento no fim do período atual. Quando false, remove um encerramento agendado.
​
string | null
Timestamp ISO 8601 em que a subscription termina. Precisa estar no futuro. Envie null para remover o prazo — a subscription volta a renovar indefinidamente.Use apenas um entre cancel_at e cancel_at_period_end na mesma requisição. Alterar a data reagenda o encerramento.
​
object
Detalhes do cancelamento. Aceita comment (texto livre) e feedback — um de customer_service, low_quality, missing_features, other, switched_service, too_complex, too_expensive ou unused; o significado de cada valor está no objeto Subscription. O campo reason é definido pela Chargefy e não pode ser enviado.
​
object
Metadata livre.
​
array
Alterações nos itens da assinatura. Use id para atualizar um item, deleted: true para remover, ou omita id para adicionar um novo item. A assinatura deve manter ao menos um item ativo.
​
string
Como o pró-rata das mudanças de item é faturado. Padrão: create_prorations.
  • create_prorations (padrão) — calcula o ajuste proporcional e o lança como itens pendentes, cobrados junto da próxima invoice do ciclo.
  • always_invoice — calcula o ajuste e emite uma invoice de update imediatamente. O saldo do cliente é aplicado antes da cobrança; se restar valor, um payment_intent é criado.
  • none — aplica a alteração sem nenhum ajuste proporcional; o novo valor passa a valer a partir da próxima renovação.
​
string
Define o que acontece quando o update gera uma cobrança imediata (invoice de update criada por proration_behavior: "always_invoice" com valor a cobrar). Padrão: allow_incomplete.
  • allow_incomplete (padrão) — aplica a alteração na hora e tenta cobrar a invoice de update automaticamente. Se a cobrança falhar, a alteração permanece aplicada e a invoice continua sendo tentada automaticamente — a assinatura pode ficar past_due.
  • default_incomplete — aplica a alteração e cria a invoice com o payment_intent, mas não tenta a cobrança automaticamente. Use quando você mesmo vai cuidar do pagamento, por exemplo enviando a página hospedada da invoice para o cliente.
  • pending_if_incomplete — não aplica a alteração na hora: ela fica retida em pending_update até a invoice de update ser paga. Se a invoice não for paga até pending_update.expires_at, a alteração é descartada e a assinatura continua como estava. Exige collection_method: "charge_automatically" e só retém a alteração quando combinado com proration_behavior: "always_invoice" e há valor a cobrar; sem cobrança imediata, o update é aplicado normalmente.
  • error_if_incomplete — recusa o update com erro 402 se ele geraria cobrança imediata com valor devido; nada é alterado. Use para garantir que só passem alterações que não cobram nada na hora.
​
string
Timestamp ISO 8601 usado para calcular o pró-rata. Não pode ser usado com proration_behavior: "none".

​
Limitações

Assinaturas com status: "canceled" ou status: "incomplete_expired" não aceitam mudança de itens, cobrança, trial ou ciclo. Nesses estados, apenas metadata, cancellation_details e cancellation_reason podem ser atualizados. Updates de item mantêm a cadência recorrente da assinatura. O novo preço precisa ter a mesma moeda, o mesmo intervalo e estar ativo. Para alterar o valor recorrente, crie ou selecione outro preço; o unit_amount de um preço existente não é editado no update da assinatura.

​
Encerrar no fim do período

Use cancel_at_period_end: true quando o cliente deve manter acesso até current_period_end. A assinatura continua com status: "active" até o corte, cancel_at aponta para o fim do período e a mudança dispara subscription.updated. Para desfazer o agendamento antes do corte, envie cancel_at_period_end: false.

​
Encerrar em uma data

Use cancel_at quando o término tem data combinada — fim de vigência de um contrato, por exemplo. A assinatura continua ativa e faturando normalmente até lá, e encerra na data sem nenhuma ação posterior. Se a data cair no meio de um período já pago, o tempo não usado é creditado no saldo do cliente conforme proration_behavior. Se cair no fim do período, não há crédito — não sobrou tempo a devolver. Envie cancel_at: null para remover o prazo.

​
Atualizar atributos

​
Atualizar itens

Alterações em price, price_data, quantity, adição ou remoção de item geram pró-rata por padrão. create_prorations cria invoice_items pendentes para a próxima invoice; always_invoice cria uma invoice de update imediatamente; none aplica a alteração sem criar pró-rata. Descontos vigentes aplicáveis entram no valor líquido usado no cálculo. As linhas de pró-rata não recebem o desconto uma segunda vez: o abatimento já está incorporado ao próprio valor. Com desconto de 100%, o ajuste é zero e nenhuma cobrança imediata é criada. Em assinaturas em período de teste, os itens são atualizados sem ajuste proporcional do ciclo atual. A cobrança recorrente passa a considerar o novo conjunto de itens quando o trial terminar. Use payment_behavior: "pending_if_incomplete" junto de proration_behavior: "always_invoice" quando a alteração só deve ser aplicada depois do pagamento da invoice de update. Enquanto a cobrança não fecha, a subscription retorna pending_update com invoice, expires_at e subscription_items. Quando always_invoice cria uma invoice positiva, o saldo do cliente é aplicado antes da cobrança. Se a invoice já ficar quitada, os eventos de criação e pagamento da invoice são enviados. Se houver valor a cobrar, um payment intent é criado para a cobrança.

​
Resposta

200 OK com o objeto subscription completo — mesmo shape de GET /v1/subscriptions/:id.