Gerenciar produtos e preços

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.

Dashboard de demonstração da Chargefy no Catálogo de produtos, com o botão Novo produto, filtros de status e oito produtos ativos — O Catálogo de produtos reúne as ofertas da organização e mostra o preço padrão e a existência de condições alternativas.

Descreva a oferta

Informe nome e descrição. O nome aparece nas superfícies de venda; a descrição aceita Markdown para organizar textos maiores.

Adicione uma imagem

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.

Defina o primeiro preço

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.

Complete a apresentação

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.

Revise e crie

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.

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 com purpose=product_image. URLs externas são rejeitadas.

O contrato completo está em Criar um produto.

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.

Dashboard de demonstração da Chargefy na aba Preços do produto Aurora Starter, com preços mensal e anual e os indicadores Ativo e Padrão — Na aba Preços, o produto Aurora Starter reúne as condições mensal e anual e identifica qual delas é o preço padrão.

Clique em Adicionar preço

Escolha um rótulo interno que ajude a reconhecer a condição, como Mensal, Anual ou Early Bird.

Defina valor e tipo

Escolha cobrança única ou recorrente. O valor pode ser gratuito ou, quando positivo, deve ser de pelo menos R$ 5,00.

Configure a recorrência

Para preços recorrentes, selecione a cadência e informe o trial padrão em dias quando ele fizer parte da oferta.

Escolha se será o padrão

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:

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:

Crie o novo Price

Use o mesmo Product e informe o novo valor, cadência ou trial.

Torne-o padrão

Faça isso se a nova condição deve ser sugerida para vendas futuras.

Arquive o Price anterior

Defina is_active: false para tirá-lo de novos fluxos sem apagar o histórico.

Decida o que fazer com assinaturas atuais

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 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:

salve o ID prod_* ou price_* correspondente em seu banco;
use metadata para manter uma referência adicional à origem;
atualize os dados comerciais do Product quando nome ou apresentação mudar;
crie outro Price quando valor ou cadência mudar;
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

Como produtos e preços funcionam

Revise a modelagem antes de ampliar o catálogo.

Criar um produto pela API

Consulte parâmetros, resposta e erros do endpoint.

Criar um preço pela API

Veja todas as cadências e opções aceitas.

Atualizar uma assinatura

Troque itens e controle o comportamento de pró-rata.

Comece aqui

Primeiros passos

Migração

Gerenciar produtos e preços

Criar um produto no Dashboard

Criar um produto pela API

Adicionar e organizar preços

Definir o preço padrão

Alterar valor, cadência ou trial

Editar e arquivar produtos

Comportamento tributário

Sincronizar um catálogo externo

Chargefy for Platforms

Próximos passos

Como produtos e preços funcionam

Criar um produto pela API

Criar um preço pela API

Atualizar uma assinatura

​Criar um produto no Dashboard

​Criar um produto pela API

​Adicionar e organizar preços

​Definir o preço padrão

​Alterar valor, cadência ou trial

​Editar e arquivar produtos

​Comportamento tributário

​Sincronizar um catálogo externo

​Chargefy for Platforms

​Próximos passos

Como produtos e preços funcionam

Criar um produto pela API

Criar um preço pela API

Atualizar uma assinatura

Criar um produto no Dashboard

Criar um produto pela API

Adicionar e organizar preços

Definir o preço padrão

Alterar valor, cadência ou trial

Editar e arquivar produtos

Comportamento tributário

Sincronizar um catálogo externo

Chargefy for Platforms

Próximos passos