Pular para o conteúdo principal
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 na menor unidade da moeda (centavos em brl).
integer
Subtotal do item na menor unidade da moeda (centavos em brl) (unit_amount × quantity).
integer
Desconto aplicado ao item na menor unidade da moeda (centavos em brl).
integer
Imposto aplicado ao item na menor unidade da moeda (centavos em brl).
integer
Total do item na menor unidade da moeda (centavos em brl) (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.