> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugtopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Planos

> Criação e gerenciamento de planos de assinatura.

## Criar plano

`POST /api/v1/subscriptions/plans` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "name": "Pro Mensal",
  "description": "Acesso completo à plataforma",
  "amount": 2990,
  "currency": "BRL",
  "interval": "monthly",
  "interval_count": 1,
  "trial_period_days": 7,
  "billing_day": 5,
  "min_card_months": 3
}
```

| Campo               | Tipo                      | Obrigatório | Descrição                                                                                                       |
| ------------------- | ------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `name`              | string (max 255)          | sim         | Nome do plano                                                                                                   |
| `description`       | string (max 1000)         | não         | Descrição exibida ao cliente                                                                                    |
| `amount`            | inteiro (centavos)        | sim         | Valor do ciclo em centavos (ex: `2990` = R\$ 29,90)                                                             |
| `currency`          | string (3 chars)          | não         | Moeda — padrão `BRL`                                                                                            |
| `interval`          | `weekly\|monthly\|yearly` | sim         | Frequência de cobrança                                                                                          |
| `interval_count`    | inteiro (1–365)           | não         | Multiplicador do intervalo — padrão `1` (ex: `2` + `monthly` = a cada 2 meses)                                  |
| `trial_period_days` | inteiro (0–365)           | não         | Dias de trial gratuito antes da primeira cobrança                                                               |
| `billing_day`       | inteiro (1–28)            | não         | Dia fixo de cobrança no mês/ano. Para `weekly` é ignorado. Se omitido, usa o dia da criação da assinatura       |
| `min_card_months`   | inteiro (1–120)           | não         | Validade mínima do cartão em meses a partir de hoje. Impede criação de assinaturas com cartões prestes a vencer |

<Warning>
  `billing_day` é sempre limitado a **28** para garantir compatibilidade com todos os meses. Dias 29, 30 e 31 não são aceitos.
</Warning>

**Resposta `201`:**

```json theme={null}
{
  "id": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
  "name": "Pro Mensal",
  "description": "Acesso completo à plataforma",
  "amount": 2990,
  "currency": "BRL",
  "interval": "monthly",
  "interval_count": 1,
  "trial_period_days": 7,
  "billing_day": 5,
  "min_card_months": 3,
  "is_active": true,
  "created_at": "2026-06-25T12:00:00+00:00",
  "updated_at": "2026-06-25T12:00:00+00:00"
}
```

***

## Atualizar plano

`PUT /api/v1/subscriptions/plans/{uuid}` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "name": "Pro Mensal Plus",
  "description": "Novo benefício incluído",
  "billing_day": 10,
  "trial_period_days": 14,
  "min_card_months": 6,
  "is_active": true
}
```

<Warning>
  **Não é possível alterar** `amount`, `currency`, `interval` ou `interval_count` após a criação. Para mudar o valor ou a frequência, crie um novo plano e migre as assinaturas via [troca de plano](/subscriptions/management#trocar-plano).
</Warning>

***

## Listar planos

`GET /api/v1/subscriptions/plans` — requer `X-Client-ID` + `X-API-Key`.

Retorna a lista de planos da empresa. Planos inativos (`is_active: false`) são incluídos.

***

## Deletar plano

`DELETE /api/v1/subscriptions/plans/{uuid}` — requer `X-Client-ID` + `X-API-Key`.

Soft-delete. Não é possível deletar um plano com assinaturas ativas.