> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Gerenciar produtos e preços
> Crie, edite, organize e arquive o catálogo pelo Dashboard ou pela API da Chargefy.
Gerencie o catálogo pelo Dashboard quando uma pessoa do time cadastra e revisa
as ofertas. Use a API quando produtos e valores nascem no seu sistema ou
precisam ser sincronizados em escala.
| Caminho | Melhor para | Você controla |
| ------------- | --------------------------------------------------- | -------------------------------------------------------------------------- |
| **Dashboard** | Criação manual, ajustes pontuais e revisão visual. | Produto, imagem, preço inicial, novos preços, preço padrão e arquivamento. |
| **API** | Catálogos externos, automações e operações em lote. | Os mesmos recursos, além de criação sem preço e correlação por `metadata`. |
## Criar um produto no Dashboard
No Dashboard, escolha a organização, abra **Produtos** e clique em **Novo
produto**.
Informe nome e descrição. O nome aparece nas superfícies de venda; a
descrição aceita Markdown para organizar textos maiores.
Escolha uma foto na galeria do Unsplash ou envie um arquivo próprio. Antes
de concluir, ajuste o recorte quadrado que aparecerá no catálogo e nos
checkouts. No upload, são aceitos PNG, JPG, WebP, GIF, BMP, HEIC e HEIF de
até 20 MB; o Dashboard prepara uma versão WebP de até 640×640, normalmente
abaixo de 300 KB. Fotos da galeria continuam hospedadas pelo Unsplash e
exibem o crédito do autor na prévia.
Escolha compra única ou um ciclo recorrente, informe um valor fixo ou
gratuito e, em recorrência, configure o trial padrão quando necessário.
Adicione até 15 destaques comerciais e use metadados para guardar
referências do seu sistema. Os destaques são apenas visuais: não liberam
permissões nem alteram a cobrança.
Confira a prévia e clique em **Criar produto**. O primeiro Price se torna a
condição padrão do Product.
O Dashboard cria os preços em BRL e oferece os ciclos mensal, trimestral,
semestral e anual. Use a API quando precisar de uma cadência válida que não
aparece entre esses atalhos.
## Criar um produto pela API
`POST /v1/products` aceita o Product e seus Prices no mesmo request. No exemplo
abaixo, o primeiro item de `prices[]` se torna `default_price`.
```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/products" \
-H "Authorization: Bearer {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"description": "Acesso completo à plataforma",
"marketing_features": [
{ "name": "Relatórios avançados" },
{ "name": "Suporte prioritário" }
],
"name": "Plano Pro",
"prices": [
{
"currency": "brl",
"name": "Mensal",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": 14
},
"type": "recurring",
"unit_amount": 9900
}
]
}'
```
Você também pode omitir `prices[]` e criar um Product sem condição de cobrança.
Quando enviar vários preços, use `default_price_index` para escolher qual deles
será o padrão; sem esse campo, o índice `0` é usado.
Pela API, `image_url` precisa ser a URL pública retornada por [`POST
/v1/files`](/api-reference/files/create) com `purpose=product_image`. URLs
externas são rejeitadas.
O contrato completo está em [Criar um produto](/api-reference/products/create).
## Adicionar e organizar preços
Abra um produto e selecione a aba **Preços**. Essa tela mostra valor, cadência,
trial, status e qual condição é a padrão.
Escolha um rótulo interno que ajude a reconhecer a condição, como Mensal,
Anual ou Early Bird.
Escolha cobrança única ou recorrente. O valor pode ser gratuito ou, quando
positivo, deve ser de pelo menos R\$ 5,00.
Para preços recorrentes, selecione a cadência e informe o trial padrão em
dias quando ele fizer parte da oferta.
Marque **Definir como preço padrão** para sugerir essa condição em novos
fluxos que partem do Product.
Pela API, crie uma nova condição com `POST /v1/prices`:
```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/prices" \
-H "Authorization: Bearer {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"currency": "brl",
"name": "Anual",
"product_id": "prod_6ye4ZdoNH56nZZC5",
"recurring": {
"interval": "year",
"interval_count": 1,
"trial_period_days": 14
},
"set_as_default": true,
"type": "recurring",
"unit_amount": 99000
}'
```
## Definir o preço padrão
O `default_price` precisa apontar para um Price do próprio Product. Você pode
defini-lo em três momentos:
| Momento | Como |
| ------------------ | ------------------------------------------------------------------------------------ |
| Ao criar o Product | `default_price_index` escolhe um item de `prices[]`. |
| Ao criar um Price | `set_as_default: true` publica a nova condição como padrão. |
| Depois | No Dashboard, use **Tornar padrão**; na API, atualize `default_price_id` do Product. |
Alterar o padrão afeta apenas novos fluxos. Assinaturas e documentos financeiros
existentes continuam com a condição que receberam na criação.
## Alterar valor, cadência ou trial
Os campos financeiros de um Price são imutáveis para preservar o histórico.
Você pode editar nome interno, status, comportamento tributário e `metadata`,
mas não pode sobrescrever valor, moeda, tipo, recorrência, trial padrão ou
Product relacionado.
Para mudar uma condição:
Use o mesmo Product e informe o novo valor, cadência ou trial.
Faça isso se a nova condição deve ser sugerida para vendas futuras.
Defina `is_active: false` para tirá-lo de novos fluxos sem apagar o
histórico.
Elas continuam no Price antigo. Atualize os itens explicitamente somente
quando o contrato do cliente também precisar mudar.
Trocar o Price de uma assinatura pode gerar crédito ou cobrança proporcional.
Revise o [pró-rata](/payments/subscription-proration) antes de migrar clientes
ativos.
## Editar e arquivar produtos
No Product, use **Editar produto** para atualizar nome, descrição, imagem,
destaques e metadados. O preço padrão é gerenciado na aba **Preços**.
Arquivar um Product impede novas compras e assinaturas, mas não altera clientes
atuais. Você pode filtrar o catálogo por **Ativos** ou **Arquivados** e reativar
uma oferta quando necessário.
Os endpoints `DELETE` aplicam o comportamento seguro automaticamente:
| Recurso | Nunca foi usado | Já possui referências |
| ------- | ------------------------------------- | ----------------------------------- |
| Product | É removido e retorna `deleted: true`. | É arquivado com `is_active: false`. |
| Price | É removido e retorna `deleted: true`. | É arquivado com `is_active: false`. |
## Comportamento tributário
`tax_behavior` pode ser `unspecified`, `inclusive` ou `exclusive`. Hoje esse
campo é declarativo: registra como o imposto se relaciona ao valor, mas não
calcula nem adiciona tributos automaticamente à cobrança.
## Sincronizar um catálogo externo
Se a fonte de verdade está no seu sistema:
1. salve o ID `prod_*` ou `price_*` correspondente em seu banco;
2. use `metadata` para manter uma referência adicional à origem;
3. atualize os dados comerciais do Product quando nome ou apresentação mudar;
4. crie outro Price quando valor ou cadência mudar;
5. publique o novo padrão e arquive condições que não devem entrar em novas
vendas.
Use paginação por cursor para catálogos maiores e `Idempotency-Key` em escritas
que podem ser repetidas. Os eventos `product.created`, `product.updated`,
`price.created` e `price.updated` ajudam a manter sistemas sincronizados.
### Chargefy for Platforms
Uma plataforma deve manter produtos e preços dentro de cada organização filha.
Com uma API key da plataforma, envie o header `Organization` para indicar qual
organização filha receberá a operação. O catálogo de uma organização não é
compartilhado automaticamente com as demais.
## Próximos passos
Revise a modelagem antes de ampliar o catálogo.
Consulte parâmetros, resposta e erros do endpoint.
Veja todas as cadências e opções aceitas.
Troque itens e controle o comportamento de pró-rata.