Skip to main content
Adiciona um item a uma subscription existente sem substituir os itens atuais. Alterações que afetam o valor recorrente geram pró-rata por padrão. Obrigatórios: subscription e exatamente um de price ou price_data — os dois juntos ou nenhum retorna erro 400. O resto tem padrão. O item novo precisa usar a mesma moeda e o mesmo intervalo de recorrência (interval + interval_count) dos itens atuais da assinatura; um intervalo ou moeda diferente retorna erro 400.
​
string
required
Subscription que receberá o item (sub_*).
​
string
Price recorrente de catálogo (price_*), ativo. Preço one_time ou inativo retorna erro 400. Envie price ou price_data, nunca os dois.
​
object
Preço inline recorrente, quando não há price de catálogo.
​
integer
Quantidade (inteiro ≥ 1). Padrão: 1.
​
string
Desconto (disc_*) aplicado ao item.
​
string
Como o item é cobrado. Padrão: licensed.
  • licensed (padrão) — 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, define como os usage records do período são agregados na cobrança. Padrão: sum.
  • sum (padrão) — 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.
​
object
Metadata do item. Padrão {}.
​
string
Como o pró-rata do item novo é 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 — adiciona o item sem ajuste proporcional; ele passa a ser cobrado a partir da próxima renovação.
​
string
Define o que acontece quando a alteração 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 segue a régua de retentativas.
  • default_incomplete — aplica a alteração e cria a invoice com o payment_intent, mas não tenta a cobrança automaticamente.
  • pending_if_incomplete — retém a alteração em pending_update na subscription até a invoice de update ser paga; se expirar sem pagamento, a alteração é descartada. Exige collection_method: "charge_automatically".
  • error_if_incomplete — recusa a alteração com erro 402 se ela geraria cobrança imediata com valor devido; nada é alterado.
​
string
Timestamp ISO 8601 usado para calcular o pró-rata. Padrão: agora. Não pode ser combinado com proration_behavior: "none" (erro 400).

​
O que a Chargefy resolve sozinha

  • quantity — sem valor explícito, 1.
  • Moeda, valor e produto — herdados do price de catálogo quando o item usa price.
  • proration_behavior / payment_behavior — sem valor explícito, create_prorations e allow_incomplete.
  • proration_date — sem valor explícito, o momento do request.
  • usage_type / aggregate_usage — sem valor explícito, licensed e sum.
  • Totais do item — amount_subtotal, amount_discount e amount_total são calculados a partir de unit_amount × quantity e do discount.