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

# Itens da Assinatura

> Gerencie os itens de uma assinatura

Os itens de uma assinatura representam os produtos ou serviços cobrados recorrentemente. Dependendo de `applyAt`, a alteração pode ser imediata ou virar uma **mudança agendada** (resposta com objeto de scheduled change em vez do item).

## Adicionar Item

```bash cURL theme={null}
curl -X POST https://api.upag.io/v1/subscriptions/sub_abc123xyz/items \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "price": "price_def456ghi",
    "quantity": 1,
    "applyAt": "now"
  }'
```

### Parâmetros — Adicionar Item

<ParamField path="subscriptionId" type="string" required>
  ID único da assinatura, começando com `sub_`.
</ParamField>

<ParamField body="price" type="string" required>
  ID do preço (`price_...`) a ser adicionado.
</ParamField>

<ParamField body="quantity" type="integer" required>
  Quantidade (inteiro, mínimo `1`).
</ParamField>

<ParamField body="applyAt" type="string">
  Opcional. `now` (padrão) ou `period_end` para aplicar na renovação.
</ParamField>

### Resposta — Adicionar Item

`201` com o item criado **ou** com uma mudança agendada, conforme a regra de negócio. Quando for o item, o formato segue o recurso de item da assinatura (ex.: `id`, `subscriptionId`, `productId`, `priceId`, `quantity`, etc.).

***

## Atualizar Item

```bash cURL theme={null}
curl -X PUT https://api.upag.io/v1/subscriptions/sub_abc123xyz/items/si_abc123xyz \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 2,
    "applyAt": "now"
  }'
```

É obrigatório enviar **pelo menos um** de `price` ou `quantity`.

### Parâmetros — Atualizar Item

<ParamField path="subscriptionId" type="string" required>
  ID único da assinatura, começando com `sub_`.
</ParamField>

<ParamField path="id" type="string" required>
  ID único do item da assinatura, começando com `si_`.
</ParamField>

<ParamField body="quantity" type="integer">
  Nova quantidade (opcional se `price` for enviado).
</ParamField>

<ParamField body="price" type="string">
  Novo ID de preço (opcional se `quantity` for enviado).
</ParamField>

<ParamField body="applyAt" type="string">
  Opcional. `now` ou `period_end`.
</ParamField>

### Resposta — Atualizar Item

`200` com o item atualizado ou com mudança agendada, no mesmo sentido do POST.

***

## Remover Item

`applyAt` é lido da **query string** (`req.query`), não do body.

```bash cURL theme={null}
curl -X DELETE "https://api.upag.io/v1/subscriptions/sub_abc123xyz/items/si_abc123xyz?applyAt=now" \
  -H "Authorization: Bearer {token}"
```

### Parâmetros — Remover Item

<ParamField path="subscriptionId" type="string" required>
  ID único da assinatura, começando com `sub_`.
</ParamField>

<ParamField path="id" type="string" required>
  ID único do item da assinatura, começando com `si_`.
</ParamField>

<ParamField query="applyAt" type="string">
  Opcional. `now` (padrão) ou `period_end`.
</ParamField>

### Resposta — Remover Item

`204 No Content` quando a remoção é imediata, ou `200` com objeto de mudança agendada quando aplicável.