Criar um preço

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "product_id": "prod_sxxtuQXNmjParup1",
    "unit_amount": 4990
  }'

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "product_id": "prod_sxxtuQXNmjParup1",
    "recurring": {
      "interval": "year"
    },
    "type": "recurring",
    "unit_amount": 99000
  }'

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "name": "Gratuito",
    "product_id": "prod_sxxtuQXNmjParup1",
    "recurring": {
      "interval": "month"
    },
    "type": "recurring",
    "unit_amount": 0
  }'

{
  "id": "price_KWs41NMrv1msFDUF",
  "object": "price",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "is_active": true,
  "livemode": true,
  "metadata": {},
  "name": "Anual",
  "product": "prod_sxxtuQXNmjParup1",
  "recurring": {
    "interval": "year",
    "interval_count": 1,
    "trial_period_days": 14,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "type": "recurring",
  "unit_amount": 99000,
  "updated_at": null
}

Cria um recurso price para um product existente. Campos de valor são imutáveis depois da criação: para mudar currency, unit_amount, type, recurring ou product_id, crie outro preço e desative o antigo. Obrigatórios: product_id, currency e unit_amount (inteiro 0 ou ≥ 500). Com type: "recurring", recurring.interval também é obrigatório. Todo o resto tem padrão. Use metadata para correlacionar o preço com IDs do seu sistema. Qualquer chave funciona; 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 dessa plataforma.

Attributes

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

Objeto livre string → string. Padrão {}.

string

Rótulo interno do preço (ex.: "Mensal", "Anual"). Envie null para deixar vazio.

string

required

ID do produto (prod_*) dono do preço.

boolean

default:"false"

Quando true, atualiza product.default_price para apontar para este preço imediatamente após a criação. Padrão: false.

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 com code: "amount_too_small".

O que a Chargefy resolve sozinha

type — sem valor explícito, o preço nasce one_time.
recurring.interval_count — sem valor explícito, 1.
is_active — o preço nasce ativo.
tax_behavior — sem valor explícito, unspecified.
metadata — sem valor explícito, {}.
livemode — herdado do produto dono.
set_as_default — com true, o default_price do produto passa a apontar para o preço recém-criado.

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "product_id": "prod_sxxtuQXNmjParup1",
    "unit_amount": 4990
  }'

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "product_id": "prod_sxxtuQXNmjParup1",
    "recurring": {
      "interval": "year"
    },
    "type": "recurring",
    "unit_amount": 99000
  }'

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "name": "Gratuito",
    "product_id": "prod_sxxtuQXNmjParup1",
    "recurring": {
      "interval": "month"
    },
    "type": "recurring",
    "unit_amount": 0
  }'

Resposta

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

Campo	Tipo	Observação
`id`	`string`	ID do preço (`price_*`)
`object`	`string`	Sempre `"price"`
`product`	`string`	Produto dono
`name`	`string \| null`	—
`type`	`string`	`one_time` ou `recurring`
`currency`	`string`	ISO 4217 minúsculo
`unit_amount`	`integer`	Minor units
`recurring`	`object \| null`	`null` em `one_time`; inclui `interval`, `interval_count`, `trial_period_days`, `usage_type`
`tax_behavior`	`string`	`unspecified`/`inclusive`/`exclusive`
`is_active`	`boolean`	—
`livemode`	`boolean`	`true` em produção; `false` em ambiente de teste
`metadata`	`object`	Eco do `metadata` enviado
`created_at`	`string`	ISO 8601
`updated_at`	`string \| null`	ISO 8601

{
  "id": "price_KWs41NMrv1msFDUF",
  "object": "price",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "is_active": true,
  "livemode": true,
  "metadata": {},
  "name": "Anual",
  "product": "prod_sxxtuQXNmjParup1",
  "recurring": {
    "interval": "year",
    "interval_count": 1,
    "trial_period_days": 14,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "type": "recurring",
  "unit_amount": 99000,
  "updated_at": null
}

Erros comuns

Status	`code`	Quando ocorre
`400`	`invalid_request`	`product_id` ausente; `currency` não é ISO de 3 letras; `unit_amount` negativo ou ausente; `type` inválido
`400`	`invalid_request`	`recurring` ausente ou `recurring.interval` inválido com `type=recurring`; `recurring.interval_count` não-inteiro, < 1 ou acima do teto da unidade; `recurring.trial_period_days` não-inteiro ou < 1
`400`	`invalid_request`	`recurring` enviado em `one_time`; `tax_behavior` inválido; `metadata` não-objeto
`404`	`resource_missing`	`product_id` não existe nesta organização

Webhook

A criação dispara price.created com o price completo em data.object.

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "product_id": "prod_sxxtuQXNmjParup1",
    "unit_amount": 4990
  }'

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "product_id": "prod_sxxtuQXNmjParup1",
    "recurring": {
      "interval": "year"
    },
    "type": "recurring",
    "unit_amount": 99000
  }'

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "brl",
    "name": "Gratuito",
    "product_id": "prod_sxxtuQXNmjParup1",
    "recurring": {
      "interval": "month"
    },
    "type": "recurring",
    "unit_amount": 0
  }'

{
  "id": "price_KWs41NMrv1msFDUF",
  "object": "price",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "is_active": true,
  "livemode": true,
  "metadata": {},
  "name": "Anual",
  "product": "prod_sxxtuQXNmjParup1",
  "recurring": {
    "interval": "year",
    "interval_count": 1,
    "trial_period_days": 14,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "type": "recurring",
  "unit_amount": 99000,
  "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