# Atualizar Item
`PUT /v1/subscriptions/:subscriptionId/items/:itemId`
**Área:** Assinaturas

**Scopes necessários:** `subscriptions/write`

**Rota canônica** para upgrade ou downgrade de plano. Altera o `priceId` ou `quantity` de um item específico.

O `subscriptionId` e `itemId` vão na URL. Informe pelo menos `priceId` ou `quantity`.

- **Upgrade** (`newTotal > currentTotal`): cobra pro-rata imediatamente (cartão) ou gera boleto/PIX assíncrono.
- **Downgrade** (`newTotal <= currentTotal`): efetivado no próximo ciclo, sem cobrança imediata.

Pré-condições: assinatura `ACTIVE`, `PAST_DUE` ou `AWAITING_PAYMENT`; item `ACTIVE`.

> Falha de pagamento retorna **400** com `PAYMENT_DECLINED` ou `PAYMENT_FAILED` (não 402).

### Path parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `subscriptionId` | **sim** | ID da assinatura (ex: sub_xxx) - required |
| `itemId` | **sim** | ID do item da assinatura (ex: item_xxx) - required |

### Request body

```json
{
  "priceId": "price_yyy",
  "quantity": 2,
  "dueDate": "2026-04-06",
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0
  },
  "expirationAfterDueDate": 30
}
```

### Campos do body

**Opcionais**

| Campo | Descrição |
|---|---|
| `priceId` | Pelo menos priceId ou quantity é obrigatório |
| `quantity` |  |
| `dueDate` | Vencimento do boleto/PIX de pro-rata (YYYY-MM-DD) |
| `boletoInstructions` | Juros, multa e desconto do boleto |
| `expirationAfterDueDate` | Dias após vencimento (0 a 60, default 30) |

### Resposta 200 — 200 upgrade

```json
{
  "success": true,
  "type": "UPGRADE",
  "chargeId": "cha_xxx",
  "prorataAmount": 33.5,
  "newAmount": 199.9
}
```

### Resposta 200 — 200 downgrade

```json
{
  "success": true,
  "type": "DOWNGRADE",
  "effectiveAt": "2024-02-01",
  "newAmount": 59.9
}
```

### Resposta 400 — 400 pagamento

```json
{
    "error": {
        "message": "Cartão recusado por saldo insuficiente",
        "code": "PAYMENT_DECLINED",
        "details": {
            "declinedCode": "insufficient_funds"
        },
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

### Resposta 404 — 404

```json
{
    "error": {
        "message": "Item não encontrado",
        "code": "ITEM_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/put-atualizar-item
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json