# Assinaturas — visão geral

## Não existe POST /v1/subscriptions

Assinaturas **não são criadas diretamente pela API**. Elas nascem quando uma cobrança com item recorrente é paga:

- `POST /v1/charges` (checkout transparente) com `items` de um preço recorrente, ou
- `POST /v1/checkouts` / `POST /v1/checkout-sessions` (link ou sessão) com um preço recorrente.

Depois do pagamento, localize a assinatura com `GET /v1/subscriptions` (filtrando, por exemplo, por `checkoutId`) ou receba o evento `subscription.created`.

## Modelo de domínio

| Entidade | Prefixo | Papel |
|---|---|---|
| Produto | `prod_` | O que é vendido |
| Preço | `price_` | Valor e recorrência de um produto |
| Assinatura | `sub_` | Contrato recorrente com um cliente |
| Item | `item_` | Linha da assinatura, ligada a um preço |
| Ciclo | — | Período de cobrança corrente |

## Status

Assinatura: `PENDING` `TRIALING` `ACTIVE` `PAST_DUE` `DEFAULT` `EXPIRED` `CANCELED` `COMPLETED` `ARCHIVED`

Item: `PENDING` `TRIALING` `AWAITING_PAYMENT` `ACTIVE` `CHARGED` `FAILED` `CANCELED` `PENDING_UPGRADE` `DEFAULT`

Tipo de item: `RECURRING` `ONE_TIME`

`paymentType`: `CREDIT_CARD` `PIX` `BOLETO` `PIX_AUTOMATICO`

Recorrência do preço: `ONE_TIME` `DAILY` `WEEKLY` `MONTHLY` `QUARTERLY` `SEMIANNUAL` `YEARLY`. `recurrenceInterval` mínimo 1 — por exemplo, `MONTHLY` com intervalo 2 é bimestral.

## Rotas

| Método | Path | Função |
|---|---|---|
| GET | `/v1/subscriptions` | Lista. Filtros: `limit`, `lastKey`, `status`, `paymentMethod`, `document`, `search`, `startDate`, `endDate`, `priceId`, `productId` |
| GET | `/v1/subscriptions/:subscriptionId` | Detalhe |
| PUT | `/v1/subscriptions/:id/items/:itemId` | Upgrade/downgrade canônico (`priceId` e/ou `quantity`) |
| POST | `/v1/subscriptions/:id/items` | Add-on |
| POST | `/v1/subscriptions/:id/prorata` | Preview de pro rata — **não cobra** |
| PATCH | `/v1/subscriptions/:id` | `{ old: { itemId }, new: { priceId } }` troca plano; `{ old: { itemId } }` cancela item |
| DELETE | `/v1/subscriptions/:id` | Cancela a assinatura. Body opcional `{ "reason" }` |

Scopes: `subscriptions/read` e `subscriptions/write`.

## Upgrade e downgrade

**Upgrade** (`newTotal > currentTotal`): cobra a diferença pro rata imediatamente. Com cartão, a cobrança é síncrona e a resposta já traz o resultado. Com Pix ou boleto, é assíncrona — a assinatura fica aguardando o pagamento da cobrança gerada.

**Downgrade**: não gera cobrança imediata; passa a valer no próximo ciclo. O evento `subscription.downgrade_scheduled` é emitido.

Antes de aplicar, use `POST /v1/subscriptions/:id/prorata` para calcular e mostrar o valor ao cliente — essa rota não cobra nada.

## Add-on

`POST /v1/subscriptions/:id/items` exige assinatura `ACTIVE` ou `PAST_DUE` e **não funciona no primeiro ciclo** (`currentCycleNumber === 1`).

## Falhas de pagamento

Nas rotas de assinatura, uma recusa retorna **400** com `PAYMENT_DECLINED` ou `PAYMENT_FAILED` — e não 402 como no checkout transparente.

## Paginação

Cursor: repita a chamada passando `lastKey` igual ao `pagination.lastKey` da resposta anterior, mantendo os mesmos filtros. `lastKey` nulo significa fim da lista.

## Eventos

Veja [Assinaturas — eventos](./assinaturas-eventos.md).