> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Preços

> Como modelar valores de cobrança na Chargefy

> [!NOTE]
>
> **Price é o objeto canônico de cobrança.**
>
> Todo pagamento (único ou recorrente) usa um `Price` atrelado a um `Product`. O **valor**, a **moeda**, a **cadência** e o **comportamento tributário** vivem aqui.
>
> Um produto pode ter vários preços; o checkout escolhe qual usar.

## Campos

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `string` | ID único do preço |
| `product_id` | `string` | FK obrigatória pra um produto |
| `type` | `'one_time' \| 'recurring'` | Tipo — compra única ou assinatura |
| `currency` | `string` | ISO 4217 em minúsculas (ex: `brl`, `usd`) |
| `unit_amount` | `integer` | Valor unitário em minor units (centavos) |
| `interval` | `'day' \| 'week' \| 'month' \| 'year'` \| `null` | Obrigatório se `type='recurring'` |
| `interval_count` | `integer` | Quantidade de intervalos entre cobranças. `null` em `one_time`, default `1` em `recurring` |
| `tax_behavior` | `'unspecified' \| 'inclusive' \| 'exclusive'` | Como o imposto se relaciona com `unit_amount` |
| `active` | `boolean` | Ativo pra novas vendas. `false` = arquivado |
| `metadata` | `object` | Metadata livre (chave/valor) |
| `zoop_recurrence_plan_id` | `string \| null` | Set pelo backend quando o seller tem Zoop configurado |

## Tipos de preço

### One-time (`type = 'one_time'`)

Cobrança única. Aceita PIX, cartão e boleto. `unit_amount` pode ser `0` (produto gratuito).

```json theme={null}
{
  "type": "one_time",
  "currency": "brl",
  "unit_amount": 4990,
  "interval": null,
  "interval_count": null
}
```

### Recurring (`type = 'recurring'`)

Assinatura. Requer `interval + interval_count`. `unit_amount` precisa ser `> 0`.

```json theme={null}
{
  "type": "recurring",
  "currency": "brl",
  "unit_amount": 9990,
  "interval": "month",
  "interval_count": 1
}
```

## Cadências suportadas

`interval` × `interval_count` dá bastante flexibilidade:

| Cadência | `interval` | `interval_count` |
| - | - | - |
| Diária | `day` | `1` |
| Semanal | `week` | `1` |
| Quinzenal | `week` | `2` |
| Mensal | `month` | `1` |
| Bimestral | `month` | `2` |
| Trimestral | `month` | `3` |
| Semestral | `month` | `6` |
| Anual | `year` | `1` |
| Bienal | `year` | `2` |

> [!NOTE]
>
> Hoje a integração Zoop honra `interval_count = 1` apenas. Outros valores são aceitos no schema e exibidos na UI, mas a cobrança cai pro padrão (1) até o ajuste Zoop. Roadmap próximo.

## Quantidade (licensed)

O `unit_amount` é **unitário**. Multiplicação por `quantity` acontece no checkout / assinatura — não no preço. É o modelo "licensed" da Stripe.

```
Total cobrado = unit_amount × quantity
```

`quantity` é persistido em:

* `checkouts.quantity` (definido pelo comprador)
* `subscription_product_prices.quantity` (persistido na assinatura, base de toda renovação)

Isso substitui o que antes era chamado de "seat-based pricing" — ver [Precificação por Quantidade](https://scaleup-c34c4386.mintlify.site/features/seat-based-pricing.md).

## Tax behavior

Declaração de como o imposto se relaciona com `unit_amount`:

* **`unspecified`** (default) — o campo existe mas não afeta cobrança. Use quando não tem posição definida.
* **`inclusive`** — imposto já incluso no valor. Ex: `unit_amount = 10000` já contém ISS/IVA.
* **`exclusive`** — imposto adicional. Ex: `unit_amount = 10000` + imposto somado no checkout.

> [!NOTE]
>
> Hoje o campo é **declarativo** e não afeta o cálculo final da cobrança. Roadmap aplica durante finalização do pagamento quando o módulo de impostos for lançado.

## Arquivar vs deletar

Prices **não são deletáveis** — cobranças históricas dependem deles. A operação correta é arquivar via `PATCH /v1/prices/:id { active: false }`.

* Preço arquivado: some de novos checkouts
* Assinaturas em curso: continuam renovando com o preço original (imutabilidade)
* Pra reativar: `PATCH { active: true }`

## Imutabilidade (padrão Stripe)

Estes campos **não podem ser alterados** depois que o preço existe:

* `currency`
* `unit_amount`
* `type`
* `interval`
* `interval_count`
* `product_id`

Pra mudar qualquer um deles: **crie um preço novo** e arquive o antigo. O `PATCH /v1/prices/:id` rejeita os campos acima com `400`.

Mutáveis via PATCH:

* `active` (arquivar/desarquivar)
* `metadata`
* `tax_behavior`

## Criar via API

**Inline com o produto** (padrão — equivalente ao `default_price_data` da Stripe):

```typescript theme={null}
await chargefy.products.create({
  name: 'Plano Pro',
  prices: [
    { currency: 'brl', unit_amount: 9990, type: 'recurring', interval: 'month' },
  ],
})
```

**Standalone** (adicionar preço a produto existente):

```bash theme={null}
curl -X POST "https://api.chargefy.io/functions/v1/create-price" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "product_id": "prod_abc123",
    "currency": "brl",
    "unit_amount": 99000,
    "type": "recurring",
    "interval": "year",
    "set_as_default": false
  }'
```

Ver [Criar Preço](https://scaleup-c34c4386.mintlify.site/api-reference/prices/create.md) e [Atualizar Preço](https://scaleup-c34c4386.mintlify.site/api-reference/prices/update.md).

## Relação com Zoop (recorrência)

Quando um preço `recurring` é criado e o seller tem conta Zoop ativa, o backend cria automaticamente um **plano de recorrência Zoop** e persiste o ID em `price.zoop_recurrence_plan_id`. Esse plano é o que a Zoop usa pra cobrar o cliente nos ciclos futuros.

Se o seller ainda não tem Zoop configurado na criação, o campo fica `null` e o plano é criado lazy na primeira venda elegível.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.