> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a Subscription Item

> Atualiza um item de subscription.

Atualiza `price`, `price_data`, `quantity`, `discount`, `usage_type`,
`aggregate_usage` ou `metadata` de um item. Mudanças de valor recorrente geram
proration por padrão.

<ParamField path="id" type="string" required>
  ID do item (`si_*`).
</ParamField>

<ParamField body="price" type="string">
  Novo price recorrente de catálogo.
</ParamField>

<ParamField body="price_data" type="object">
  Novo preço inline recorrente.
</ParamField>

<ParamField body="quantity" type="number">
  Nova quantidade.
</ParamField>

<ParamField body="discount" type="string">
  Desconto aplicado ao item. Envie `null` para remover.
</ParamField>

<ParamField body="usage_type" type="string">
  `licensed` ou `metered`.
</ParamField>

<ParamField body="aggregate_usage" type="string">
  `sum`, `last_during_period`, `last_ever` ou `max`.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata do item.
</ParamField>

<ParamField body="proration_behavior" type="string">
  `create_prorations`, `always_invoice` ou `none`. Padrão:
  `create_prorations`.
</ParamField>

<ParamField body="payment_behavior" type="string">
  Controla updates que criam cobrança imediata. Aceita `allow_incomplete`,
  `default_incomplete`, `pending_if_incomplete` ou `error_if_incomplete`.
  Padrão: `allow_incomplete`. Use `error_if_incomplete` apenas quando a
  alteração não gerar valor a cobrar imediatamente.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/subscription-items/si_123" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_behavior": "pending_if_incomplete",
      "proration_behavior": "always_invoice",
      "quantity": 3
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response 200 theme={}
  {
    "id": "si_123",
    "object": "subscription_item",
    "aggregate_usage": "sum",
    "amount_discount": 0,
    "amount_subtotal": 30000,
    "amount_tax": 0,
    "amount_total": 30000,
    "created_at": "2026-05-19T18:00:00Z",
    "currency": "brl",
    "discount": null,
    "metadata": {},
    "position": 0,
    "price": "price_pro",
    "price_data": null,
    "product": "prod_123",
    "quantity": 3,
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "subscription": "sub_123",
    "unit_amount": 10000,
    "updated_at": "2026-05-19T18:10:00Z",
    "usage_period_end": null,
    "usage_period_start": null,
    "usage_type": "licensed"
  }
  ```
</ResponseExample>