> ## 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.

# Create a Subscription Item

> Adiciona um item a uma subscription.

Adiciona um item a uma subscription existente sem substituir os itens atuais.
Alterações que afetam o valor recorrente geram proration por padrão.

<ParamField body="subscription" type="string" required>
  Subscription que receberá o item (`sub_*`).
</ParamField>

<ParamField body="price" type="string">
  Price recorrente de catálogo. Envie `price` ou `price_data`.
</ParamField>

<ParamField body="price_data" type="object">
  Preço inline recorrente. Deve incluir `product`, `currency`, `unit_amount` e
  `recurring.interval`.
</ParamField>

<ParamField body="quantity" type="number">
  Quantidade. Padrão: `1`.
</ParamField>

<ParamField body="discount" type="string">
  Desconto (`disc_*`) aplicado ao item.
</ParamField>

<ParamField body="usage_type" type="string">
  `licensed` ou `metered`. Padrão: `licensed`.
</ParamField>

<ParamField body="aggregate_usage" type="string">
  Para item `metered`, define como os registros de uso são agregados:
  `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>

<ParamField body="proration_date" type="string">
  Timestamp ISO 8601 usado para calcular a proration.
</ParamField>

<RequestExample>
  ```bash Com price de catálogo theme={}
  curl -X POST "https://api.chargefy.io/v1/subscription-items" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "price": "price_123",
      "subscription": "sub_123"
    }'
  ```

  ```bash Com price_data inline theme={}
  curl -X POST "https://api.chargefy.io/v1/subscription-items" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "price_data": {
        "product": "prod_123",
        "recurring": {
          "interval": "month"
        },
        "unit_amount": 10000
      },
      "subscription": "sub_123"
    }'
  ```
</RequestExample>

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