Skip to main content
Um subscription_item representa uma linha recorrente dentro de uma subscription. Uma subscription pode ter mais de um item, todos no mesmo ciclo recorrente. Pense na subscription como o contrato ativo com o cliente, e nos subscription_items como as linhas que compõem a cobrança recorrente: plano base, assentos, add-ons, módulos extras ou um item medido por uso. Cada item guarda o preço, quantidade, desconto próprio, modo de uso e totais daquele componente. Use esse objeto quando você precisa explicar ou alterar do que uma assinatura é feita. Exemplos comuns: Alterações em item que mudam valor recorrente podem gerar pró-rata, dependendo do proration_behavior usado no endpoint de criação, atualização ou remoção. Para mostrar o impacto antes de alterar, use Invoice Previews.

​
Objeto subscription_item

Este é o formato retornado em create, get, update, itens de list, respostas de delete quando o item ainda é representado no contrato, e dentro do array subscription_items do objeto subscription.
​
string
ID do item (si_*).
​
string
Sempre subscription_item.
​
string
Subscription dona do item (sub_*).
​
integer
Posição do item dentro da subscription, começando em 0.
​
string | null
Produto do catálogo (prod_*) por trás do preço do item. Vem null quando o item usa um preço definido na hora sem produto de catálogo.
​
string | null
Price de catálogo (price_*) usado pelo item. Vem null quando o item usa price_data.
​
object | null
Snapshot do preço definido na criação do item, quando ele não usa um price de 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.
​
number
Quantidade cobrada a cada ciclo. Em item metered, a quantidade efetiva é apurada pelos usage records no fechamento do ciclo.
​
string
Moeda do item em código ISO de 3 letras minúsculas, como brl.
​
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 recorrente do item. Vem null quando o item não é recorrente.
​
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 para correlacionar o item com o seu sistema. Quando vazio, retorna {}.
​
string
Data de criação em ISO 8601.
​
string | null
Data da última atualização em ISO 8601. Vem null enquanto o item nunca foi atualizado.

​
Como processar

Para exibir uma assinatura, liste os subscription_items em ordem de position e mostre amount_total por item junto do total da subscription. Para itens licensed, quantity é a quantidade cobrada no ciclo. Para itens metered, use usage_period_start e usage_period_end para mostrar a janela de apuração, e consulte os usage records quando precisar auditar o consumo registrado. Quando seu produto altera quantidade, plano ou add-on, gere uma invoice preview antes de aplicar a mudança. Depois de aplicar, trate a subscription atualizada e os webhooks de invoice como fonte confiável para fulfillment e cobrança.

​
Pontos de atenção

  • Todos os itens de uma subscription precisam compartilhar moeda e intervalo de recorrência.
  • price_data é snapshot inline do preço usado naquele item; ele não cria um preço reutilizável no catálogo.
  • Desconto em discount vale para aquele item. Descontos no nível da subscription ou da invoice podem aparecer em outros objetos.
  • Em item metered, registre uso com idempotência para evitar duplicidade em retentativas do seu sistema.