# Atualizar Assinatura (Item)
`PATCH /v1/subscriptions/:subscriptionId`
**Área:** Assinaturas

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

Realiza **upgrade ou downgrade** de um item da assinatura. Envie `old.itemId` do item atual e `new.priceId` (e opcionalmente `new.quantity`) do novo plano.

> Rota **canônica** para upgrade/downgrade: **Atualizar Item** (PUT). Este PATCH delega para a mesma lógica.

- **Upgrade:** gera cobrança de pro rata imediatamente (cartão) ou de forma assíncrona via webhook (PIX/boleto). O item antigo só é substituído após confirmação do pagamento.
- **Downgrade:** a mudança é agendada para o próximo ciclo de cobrança, sem cobrança imediata.

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

Case de uso:

_Como SaaS, quero permitir que meu cliente faça upgrade do plano Básico para o Pro no meio do ciclo, cobrando apenas a diferença proporcional._

### Path parameters

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

### Request body

```json
{
  "old": {
    "itemId": "item_xxx"
  },
  "new": {
    "priceId": "price_yyy",
    "quantity": 2
  }
}
```

### Campos do body

**Obrigatórios:** `old`, `old.itemId`, `new`, `new.priceId`

| Campo | Descrição |
|---|---|
| `old` |  |
| `old.itemId` | ID do item atual |
| `new` |  |
| `new.priceId` | ID do novo preço |

**Opcionais**

| Campo | Descrição |
|---|---|
| `new.quantity` | Nova quantidade (default 1) |

### Resposta 200 — 200

```json
{
  "success": true,
  "type": "UPGRADE",
  "chargeId": "cha_xxx",
  "prorataAmount": 45.0,
  "newAmount": 100.0
}
```

### Resposta 400 — 400

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

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