# Adicionar Item
`POST /v1/subscriptions/:subscriptionId/items`
**Área:** Assinaturas

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

Adiciona um novo produto ou serviço a uma assinatura já existente.

Informe o `priceId` de um preço previamente cadastrado. Para assinaturas com cartão de crédito, a cobrança é processada imediatamente. Para PIX ou boleto, a resposta inclui `payment.transactionId` — a confirmação chega via **webhook**.

Pré-condições: assinatura `ACTIVE` ou `PAST_DUE`. Antes do 1º pagamento confirmado (`currentCycleNumber === 1`), add item retorna `400`.

> `billOnNextCycle` adia a cobrança para o próximo ciclo (apenas boleto/PIX; incompatível com cartão ou `ONE_TIME`).

Case de uso:

_Como SaaS, quero adicionar um módulo extra (add-on) à assinatura de um cliente que já possui um plano base._

### Path parameters

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

### Request body

```json
{
  "priceId": "price_xxx",
  "quantity": 1,
  "type": "RECURRING",
  "billOnNextCycle": false,
  "dueDate": "2026-04-06",
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0
  },
  "expirationAfterDueDate": 30
}
```

### Campos do body

**Obrigatórios:** `priceId`

| Campo | Descrição |
|---|---|
| `priceId` | ID do preço do item |

**Opcionais**

| Campo | Descrição |
|---|---|
| `quantity` | Quantidade (default 1, mínimo 1) |
| `type` | RECURRING ou ONE_TIME (default RECURRING) |
| `billOnNextCycle` | Adia cobrança para próximo ciclo (boleto/PIX apenas) |
| `dueDate` | Vencimento do boleto/PIX de pro-rata (YYYY-MM-DD) |
| `boletoInstructions` | Para assinaturas com boleto |
| `expirationAfterDueDate` | Dias após vencimento (0 a 60, default 30) |

### Resposta 200 — 200 cartão

```json
{
  "success": true,
  "type": "ADD_ITEM",
  "chargeId": "cha_xxx",
  "amount": 49.9,
  "newAmount": 149.8
}
```

### Resposta 200 — 200 PIX

```json
{
  "success": true,
  "type": "ADD_ITEM",
  "paymentMethod": "PIX",
  "chargeId": "cha_xxx",
  "payment": {
    "emvQrCode": "..."
  }
}
```

### Resposta 400 — 400 pagamento

```json
{
    "error": {
        "message": "Cartão recusado pela operadora",
        "code": "PAYMENT_DECLINED",
        "details": {
            "declinedCode": "card_declined"
        },
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

### Resposta 400 — 400

```json
{
    "error": {
        "message": "Assinatura não está ativa",
        "code": "SUBSCRIPTION_NOT_ACTIVE",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

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