> ## 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.

# Produtos

> Modele o que você vende e atrele preços — estilo Stripe.

> [!NOTE]
>
> **Produto ≠ Preço**
>
> Na Chargefy, **Product** e **Price** são objetos separados. Um produto descreve **o que você vende**. Um preço descreve **como cobrar**. Um produto pode ter **múltiplos preços**, e `products.default_price_id` define qual deles é o padrão para fluxos que trabalham em nível de produto.

## Modelo conceitual

```mermaid theme={null}
flowchart LR
  P[Product] -- default_price_id --> DP[Price padrão]
  P --> Pm[Price mensal]
  P --> Py[Price anual]
  P --> Po[Price promocional]
```

* **Product** — entidade de catálogo. Carrega `name`, `description`, `metadata`, `is_tax_applicable` e o ponteiro `default_price_id`.
* **Price** — entidade de cobrança vinculada a um produto. Carrega `unit_amount`, `currency`, `type`, `interval`, `interval_count`, `active`, `tax_behavior`, `metadata` e `name` opcional como rótulo interno.
* **`products.default_price_id`** — resolve o preço padrão quando o fluxo parte do produto e não de um preço específico.

Ver o objeto em detalhe em [Preços](https://scaleup-c34c4386.mintlify.site/features/prices.md).

## Criar um produto

### Nome e descrição

O básico do catálogo:

* **Nome** — título do produto
* **Descrição** — texto do produto

### Ao menos um preço

Todo produto nasce com pelo menos um preço.

**1. Dashboard**

A criação no painel começa com um **preço base**. Se você quiser outras variações, normalmente adiciona depois na gestão de preços do produto.

**2. API**

A criação via API aceita `prices[]` inline. O primeiro preço vira `products.default_price_id`, ou você escolhe outro com `default_price_index`.

### Shape do preço inicial

No fluxo atual, o preço criado junto do produto segue este contrato:

* `type = 'one_time'` para compra única
* `type = 'recurring'` para cobrança recorrente
* `interval` em `day`, `week`, `month` ou `year` quando `type = 'recurring'`
* `interval_count` para cobrar a cada N intervalos
* `unit_amount` em centavos
* `unit_amount = 0` apenas para `one_time`

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

### Metadata

`metadata` existe tanto em `Product` quanto em `Price`.

Use para:

* tags internas
* mapeamento com IDs externos
* flags de catálogo
* contexto adicional para integrações

> [!NOTE]
>
> Esta página cobre **modelagem de catálogo**. Comportamento de checkout e cobrança fica nas páginas específicas de checkout, pagamentos e assinaturas.

## Múltiplos preços no mesmo produto

O padrão recomendado para variações de cobrança é um produto com vários preços.

Exemplos comuns:

* mensal + anual no mesmo plano
* compra única + versão recorrente do mesmo item
* preço padrão + preço promocional arquivado depois
* preços com `name` interno como `Mensal`, `Anual Early Bird` ou `Equipe 10+`

O `products.default_price_id` define qual preço aparece como padrão. Esse padrão pode ser trocado de duas formas:

* criando um novo preço com `set_as_default: true`
* marcando outro preço como padrão na gestão de preços do produto

Para adicionar um preço novo em um produto existente, use [Criar Preço](https://scaleup-c34c4386.mintlify.site/api-reference/prices/create.md) com `product_id`.

## Arquivar um preço sem deletar o produto

O campo canônico para disponibilidade de preço é `prices.active`.

Quando `active: false`:

* o preço sai de novos fluxos de compra
* o produto continua existindo
* o histórico continua íntegro

Para mudar valor, moeda ou cadência de um preço, siga a regra:

1. crie um preço novo
2. troque o padrão se necessário
3. arquive o antigo

Isso mantém a imutabilidade de cobrança e evita reescrever histórico.

## Atualizar um produto

No fluxo atual, trate estes campos como editáveis com segurança:

* `name`
* `description`
* `metadata`
* `is_archived`

Para alterações de preço, use os endpoints e telas de preço, não o update de produto.

## Arquivar um produto

Arquivar um produto remove o item do catálogo e dos novos fluxos de compra, mas **não apaga histórico**.

Isso é o caminho certo quando você quer tirar uma oferta de circulação sem destruir:

* vendas já registradas
* assinaturas já associadas
* eventos e auditoria do catálogo

## Impostos

A modelagem atual separa o tema em dois níveis:

* `products.is_tax_applicable` indica se o produto é tributável
* `prices.tax_behavior` descreve como o imposto se relaciona com o valor do preço

Valores suportados em `tax_behavior`:

* `unspecified`
* `inclusive`
* `exclusive`

Hoje esse campo é **declarativo**. Ele já faz parte do contrato público do preço, mas não muda o cálculo final da cobrança sozinho.

## Quantidade

`Price` é **unitário**.

A multiplicação acontece depois, no fluxo de checkout/assinatura, usando quantidade. Em termos de modelo:

```text theme={null}
Total = prices.unit_amount × checkouts.quantity
```

Se você vende por assento, licença ou unidade, o caminho é esse modelo unitário + quantidade. Ver [Precificação por Quantidade](https://scaleup-c34c4386.mintlify.site/features/seat-based-pricing.md).


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