Criar um produto

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Serviço sob consulta"
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Pro",
    "prices": [
      {
        "currency": "brl",
        "unit_amount": 9990
      }
    ]
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Pro",
    "marketing_features": [
      { "name": "Acesso ilimitado" },
      { "name": "Suporte prioritário" }
    ]
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Programa beta",
    "prices": [
      {
        "currency": "brl",
        "name": "Mensal gratuito",
        "recurring": {
          "interval": "month"
        },
        "type": "recurring",
        "unit_amount": 0
      }
    ]
  }'

{
  "id": "prod_KxBdY7EaRXHT8THT",
  "object": "product",
  "created_at": "2026-05-16T14:09:27Z",
  "default_price": null,
  "description": null,
  "image_url": null,
  "is_active": true,
  "is_tax_applicable": true,
  "livemode": true,
  "marketing_features": [],
  "metadata": {},
  "name": "Serviço sob consulta",
  "prices": [],
  "updated_at": null
}

Cria um recurso product. Você pode criar o produto sem preço e definir os valores depois via POST /v1/prices, ou enviar prices[] inline no mesmo request. Quando prices[] tem itens, o primeiro preço do array vira default_price, ou use default_price_index para escolher outro. Só name é obrigatório. Todo o resto tem padrão ou é resolvido pela Chargefy — inclusive o default_price quando você envia prices[]. Use metadata para correlacionar o produto com IDs do seu sistema. Qualquer chave funciona (ex.: sku, reference_id); o objeto inteiro é retornado em todos os webhooks.

Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o header Organization: <organization_id> apontando para uma organização conectada ativa.

Attributes

integer

default:"0"

Índice do preço em prices[] que vira default_price. Padrão: 0 (o primeiro preço do array). Enviado sem prices[], ou fora do range do array, retorna erro 400.

string

Descrição livre. Envie null para deixar vazio.

string

URL retornada por POST /v1/files com purpose=product_image. Envie null para deixar vazio. URLs externas não são aceitas.

boolean

default:"true"

Indica se o produto é tributável. Padrão: true.

array

Lista de recursos de marketing exibidos ao comprador nas superfícies de venda. No máximo 15 itens. Padrão [].

Show marketing_features

string

required

Texto do recurso. Até 80 caracteres.

object

Objeto livre string → string para correlacionar com o seu sistema. Padrão {}.

string

required

Nome do produto exibido em checkout, faturas e webhooks.

array

Lista opcional de preços inline. Cada item segue o mesmo shape de POST /v1/prices (sem product_id). Quando omitido ou vazio, o produto nasce com default_price: null e prices: [].

Show price

string

required

Código ISO 4217 em minúsculas. Ex.: brl, usd.

object

Obrigatório quando type é recurring. Enviar recurring com type: "one_time" retorna erro 400.

Show Campos de recurring

string

required

Intervalo de recorrência.

Valor	Descrição
`day`	Cobrança diária.
`week`	Cobrança semanal.
`month`	Cobrança mensal.
`year`	Cobrança anual.

integer

default:"1"

Quantidade de intervalos entre cobranças. Inteiro ≥ 1. Padrão: 1. Máximo por unidade: day=1460, week=208, month=48, year=4. Trimestral é month + 3; semestral é month + 6.

integer

Trial padrão em dias (inteiro ≥ 1) para assinaturas criadas a partir deste preço.

boolean

default:"true"

Se o preço fica disponível para novas vendas. Padrão: true.

object

Metadata livre do preço. Padrão {}.

string

Rótulo interno do preço. Envie null para deixar vazio.

string

default:"unspecified"

Como o imposto se relaciona ao valor. Padrão: unspecified.

Valor	Descrição
`unspecified`	Comportamento de imposto não definido.
`inclusive`	Imposto já incluso no valor.
`exclusive`	Imposto somado ao valor.

string

default:"one_time"

Forma de cobrança do preço. Padrão: one_time.

Valor	Descrição
`one_time`	Compra única.
`recurring`	Cobrança que se repete em um intervalo definido.

integer

required

Valor unitário em minor units (centavos). 0 é válido para one_time e recurring (preço gratuito). Valor positivo tem mínimo 500 (R$ 5,00) — entre 1 e 499 retorna 400.

O que a Chargefy resolve sozinha

default_price — com prices[], aponta para prices[default_price_index] (o primeiro, por padrão); sem prices[], fica null.
is_active — o produto nasce ativo.
is_tax_applicable — sem valor explícito, true.
marketing_features e metadata — sem valor explícito, [] e {}.
Preços inline — cada item de prices[] herda os mesmos padrões de POST /v1/prices: type one_time, interval_count 1, tax_behavior unspecified, is_active true.
Webhooks — além de product.created, cada preço inline dispara o próprio price.created.

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Serviço sob consulta"
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Pro",
    "prices": [
      {
        "currency": "brl",
        "unit_amount": 9990
      }
    ]
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Pro",
    "marketing_features": [
      { "name": "Acesso ilimitado" },
      { "name": "Suporte prioritário" }
    ]
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Programa beta",
    "prices": [
      {
        "currency": "brl",
        "name": "Mensal gratuito",
        "recurring": {
          "interval": "month"
        },
        "type": "recurring",
        "unit_amount": 0
      }
    ]
  }'

Resposta

200 OK com o objeto product completo. Todo campo declarado pelo DTO público é sempre retornado; vazio é null, {} ou [].

Campo	Tipo	Observação
`id`	`string`	ID do produto (`prod_*`)
`object`	`string`	Sempre `"product"`
`name`	`string`	—
`description`	`string \| null`	—
`image_url`	`string \| null`	—
`is_tax_applicable`	`boolean`	—
`default_price`	`string \| null`	Aponta para um item de `prices[]`, ou `null` quando o produto ainda não tem preço padrão
`is_active`	`boolean`	`false` quando arquivado
`livemode`	`boolean`	`true` em produção; `false` em ambiente de teste
`marketing_features`	`array`	Lista de recursos de marketing (`{ name }`). `[]` quando vazio
`metadata`	`object`	Eco do `metadata` enviado
`created_at`	`string`	ISO 8601
`updated_at`	`string \| null`	ISO 8601
`prices`	`array`	Lista de objetos `price` completos (mesmo shape de `GET /v1/prices/:id`)

{
  "id": "prod_KxBdY7EaRXHT8THT",
  "object": "product",
  "created_at": "2026-05-16T14:09:27Z",
  "default_price": null,
  "description": null,
  "image_url": null,
  "is_active": true,
  "is_tax_applicable": true,
  "livemode": true,
  "marketing_features": [],
  "metadata": {},
  "name": "Serviço sob consulta",
  "prices": [],
  "updated_at": null
}

Erros comuns

Status	`code`	Quando ocorre
`400`	`invalid_request`	`name` ausente; `prices` não-array; `metadata` não-objeto; `default_price_index` sem `prices[]` ou fora do range
`400`	`invalid_request`	`marketing_features` não-array; mais de 15 itens; `marketing_features[N].name` ausente/vazio ou acima de 80 caracteres
`400`	`invalid_request`	`image_url` não aponta para um `file` ativo de `purpose=product_image` da organização
`400`	`invalid_request`	Em `prices[N]`: `currency` não é ISO de 3 letras; `unit_amount` negativo ou ausente; `type` inválido; `recurring.interval` ausente para `recurring`; `recurring.interval_count` não-inteiro, < 1 ou acima do teto da unidade; `recurring` em `one_time`; `tax_behavior` inválido

Webhook

A criação dispara product.created com o product completo em data.object. Cada preço inline também dispara price.created.

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Serviço sob consulta"
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Pro",
    "prices": [
      {
        "currency": "brl",
        "unit_amount": 9990
      }
    ]
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Pro",
    "marketing_features": [
      { "name": "Acesso ilimitado" },
      { "name": "Suporte prioritário" }
    ]
  }'

curl -X POST "https://api.chargefy.io/v1/products" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Programa beta",
    "prices": [
      {
        "currency": "brl",
        "name": "Mensal gratuito",
        "recurring": {
          "interval": "month"
        },
        "type": "recurring",
        "unit_amount": 0
      }
    ]
  }'

{
  "id": "prod_KxBdY7EaRXHT8THT",
  "object": "product",
  "created_at": "2026-05-16T14:09:27Z",
  "default_price": null,
  "description": null,
  "image_url": null,
  "is_active": true,
  "is_tax_applicable": true,
  "livemode": true,
  "marketing_features": [],
  "metadata": {},
  "name": "Serviço sob consulta",
  "prices": [],
  "updated_at": null
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Erros comuns

Webhook

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Resposta

​Erros comuns

​Webhook

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Erros comuns

Webhook