Skip to main content
Atualiza price, price_data, quantity, discount, usage_type, aggregate_usage ou metadata de um item. Mudanças de valor recorrente geram pró-rata por padrão.
​
string
required
ID do item (si_*).
​
string
Novo price recorrente de catálogo.
​
object
Novo preço inline recorrente.
​
number
Nova quantidade.
​
string
Desconto aplicado ao item. Envie null para remover.
​
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, define 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.
​
object
Metadata do item.
​
string
Como o pró-rata da alteração é 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 ajuste proporcional; o novo valor passa a valer 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.