Criar um desconto

curl -X POST "https://api.chargefy.io/v1/discounts" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday 20%",
    "percent_off_basis_points": 2000,
    "type": "percentage"
  }'

curl -X POST "https://api.chargefy.io/v1/discounts" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_off": 1500,
    "currency": "brl",
    "name": "Black Friday R$15",
    "type": "fixed"
  }'

{
  "id": "disc_jJrDQKyy9HGGvPap",
  "object": "discount",
  "amount_off": null,
  "applies_to": {
    "products": [
      "prod_24qYPAnKXSb2wTDs"
    ]
  },
  "created_at": "2026-05-21T12:00:00Z",
  "currency": null,
  "duration": "once",
  "duration_in_months": null,
  "expires_at": null,
  "is_active": true,
  "livemode": true,
  "max_redemptions": 500,
  "metadata": {},
  "name": "Black Friday 20%",
  "percent_off_basis_points": 2000,
  "redemptions_count": 0,
  "starts_at": null,
  "type": "percentage",
  "updated_at": null,
  "valid": true
}

Cria um discount. Para um cupom digitável pelo comprador, crie depois um discount_code com discount_id. Obrigatórios: name e type. O campo de valor depende do type — exatamente um dos dois formatos: type=fixed exige amount_off + currency; type=percentage exige percent_off_basis_points. Enviar o formato errado para o type escolhido (ou nenhum) retorna 400. Todo o resto tem default.

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

Valor fixo em centavos (inteiro positivo). Obrigatório quando type=fixed; só válido com type=fixed.

object

Escopo do desconto. Use products com IDs prod_*; array vazio (padrão) aplica a todos os produtos. Todos os IDs precisam ser de produtos ativos da organização — ID desconhecido ou de outra organização retorna 400. Quando há produtos definidos, o abatimento é calculado somente sobre o subtotal das linhas elegíveis.

string

Código ISO de 3 letras (normalizado para minúsculas). Obrigatório quando type=fixed; só válido com type=fixed.

string

default:"once"

Duração do desconto em cobranças recorrentes.

Valor	Descrição
`once`	Aplica o desconto apenas na primeira cobrança.
`forever`	Aplica o desconto em todas as cobranças.
`repeating`	Aplica o desconto pelo número de meses definido em `duration_in_months`.

integer

Número de meses (inteiro positivo). Obrigatório quando duration=repeating; para once e forever é ignorado e fica null.

string

Data ISO 8601 de expiração. Padrão: null (sem expiração). Precisa ser posterior a starts_at quando ambos são enviados.

boolean

default:"true"

Se o desconto nasce ativo. Padrão: true.

integer

Limite total de aplicações (inteiro positivo). Padrão: null (sem limite).

object

Objeto livre para correlação. Padrão: {}.

string

required

Nome do desconto.

integer

Percentual em basis points, de 1 a 10000 (2000 = 20%). Obrigatório quando type=percentage; só válido com type=percentage.

string

Data ISO 8601 a partir da qual o desconto passa a valer. Padrão: null (vale imediatamente). Precisa ser anterior a expires_at quando ambos são enviados — senão 400.

string

required

Tipo econômico do desconto.

Valor	Descrição
`percentage`	Desconto percentual, definido em `percent_off_basis_points`.
`fixed`	Desconto de valor fixo, definido em `amount_off`.

O que a Chargefy resolve sozinha

duration nasce once quando omitido.
O campo de valor do tipo não usado é zerado: type=fixed deixa percent_off_basis_points como null; type=percentage deixa amount_off e currency como null.
duration_in_months fica null quando duration não é repeating.
is_active nasce true e redemptions_count nasce 0.
currency é normalizada para minúsculas.

curl -X POST "https://api.chargefy.io/v1/discounts" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday 20%",
    "percent_off_basis_points": 2000,
    "type": "percentage"
  }'

curl -X POST "https://api.chargefy.io/v1/discounts" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_off": 1500,
    "currency": "brl",
    "name": "Black Friday R$15",
    "type": "fixed"
  }'

Resposta

200 OK com o objeto discount completo.

{
  "id": "disc_jJrDQKyy9HGGvPap",
  "object": "discount",
  "amount_off": null,
  "applies_to": {
    "products": [
      "prod_24qYPAnKXSb2wTDs"
    ]
  },
  "created_at": "2026-05-21T12:00:00Z",
  "currency": null,
  "duration": "once",
  "duration_in_months": null,
  "expires_at": null,
  "is_active": true,
  "livemode": true,
  "max_redemptions": 500,
  "metadata": {},
  "name": "Black Friday 20%",
  "percent_off_basis_points": 2000,
  "redemptions_count": 0,
  "starts_at": null,
  "type": "percentage",
  "updated_at": null,
  "valid": true
}

curl -X POST "https://api.chargefy.io/v1/discounts" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday 20%",
    "percent_off_basis_points": 2000,
    "type": "percentage"
  }'

curl -X POST "https://api.chargefy.io/v1/discounts" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_off": 1500,
    "currency": "brl",
    "name": "Black Friday R$15",
    "type": "fixed"
  }'

{
  "id": "disc_jJrDQKyy9HGGvPap",
  "object": "discount",
  "amount_off": null,
  "applies_to": {
    "products": [
      "prod_24qYPAnKXSb2wTDs"
    ]
  },
  "created_at": "2026-05-21T12:00:00Z",
  "currency": null,
  "duration": "once",
  "duration_in_months": null,
  "expires_at": null,
  "is_active": true,
  "livemode": true,
  "max_redemptions": 500,
  "metadata": {},
  "name": "Black Friday 20%",
  "percent_off_basis_points": 2000,
  "redemptions_count": 0,
  "starts_at": null,
  "type": "percentage",
  "updated_at": null,
  "valid": true
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Criar um desconto

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Resposta

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta