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

# Atualizar item

> Troca o preço ou a quantidade de um item, agora ou na próxima renovação

Altera o preço e/ou a quantidade de um item da assinatura. Com `applyAt: "now"` (padrão) a mudança vale na hora; com `applyAt: "period_end"` ela vira uma [mudança agendada](./scheduled-changes), aplicada na próxima renovação.

A alteração não gera fatura nem cobrança proporcional: o novo valor passa a valer na próxima renovação.

Permissão: `subscription.write`. Apenas chave secreta (`sk_…`).

<Note>
  Os exemplos usam o sandbox (`https://api.upag.dev/v1`). Em produção use `https://api.upag.io/v1` com `sk_live_…`.
</Note>

## Endpoint

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.upag.dev/v1/subscriptions/9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36/items/c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07 \
    -H "Authorization: Bearer sk_test_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "quantity": 3,
      "applyAt": "period_end"
    }'
  ```

  ```javascript Node.js SDK theme={null}
  import { Upag } from 'upag';

  const upag = new Upag('sk_test_your_api_key');

  const result = await upag.subscriptions.updateItem(
    '9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36',
    'c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07',
    { quantity: 3, applyAt: 'period_end' },
  );
  ```
</CodeGroup>

## Parâmetros

<ParamField path="subscriptionId" type="string (uuid)" required>
  ID da assinatura.
</ParamField>

<ParamField path="itemId" type="string (uuid)" required>
  ID do item (`items[].id` da assinatura).
</ParamField>

<ParamField body="price" type="string (uuid)">
  UUID do novo [preço](../prices/reference): `recurring`, com o mesmo `interval`, `intervalCount` e moeda da assinatura.
</ParamField>

<ParamField body="quantity" type="integer">
  Nova quantidade, mínimo 1.
</ParamField>

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

Envie pelo menos `price` ou `quantity`.

## Resposta

`200 OK`. Com `now`, é o item já atualizado; com `period_end`, é a [mudança agendada](./scheduled-changes).

```json Response (applyAt: now) theme={null}
{
  "id": "c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07",
  "product": "7d2b5e90-1c34-4a68-b9f7-0e3a6c8d1f25",
  "price": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61",
  "name": "Plano mensal",
  "amount": 9900,
  "quantity": 3,
  "totalAmount": 29700,
  "createdAt": "2026-10-07T19:00:00.000Z",
  "updatedAt": "2026-10-12T14:20:00.000Z"
}
```

```json Response (applyAt: period_end) theme={null}
{
  "id": "2b7d4f91-8e06-4c53-a1d8-5f3c9e0a6b72",
  "subscription": "9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36",
  "operation": "update",
  "item": "c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07",
  "price": null,
  "quantity": 3,
  "createdAt": "2026-10-12T14:20:00.000Z"
}
```

## Erros

| Status | Código | Quando |
| - | - | - |
| `404` | `SUBSCRIPTION_NOT_FOUND` | A assinatura não existe ou é de outra conta |
| `404` | `SUBSCRIPTION_ITEM_NOT_FOUND` | O item não pertence à assinatura |
| `404` | `PRICE_NOT_FOUND` / `PRODUCT_NOT_FOUND` | O novo preço, ou o produto dele, não existe na conta |
| `400` | `SUBSCRIPTION_NOT_EDITABLE` | A assinatura está `canceled` ou `void` |
| `400` | `SUBSCRIPTION_PRICE_MISMATCH` | Intervalo ou moeda do novo preço diferentes da assinatura |
| `422` | `VALIDATION_FAILED` | Nem `price` nem `quantity` enviados |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.