POST /api/v1/sdk/organizations/:orgId/discounts

Cria um desconto em nome de uma sub-organização filha, gerenciado pela organização pai autenticada.

Cria um desconto para uma sub-organização filha. A organização autenticada deve ser a organização pai da orgId informada. Suporta dois tipos: fixed (valor fixo em centavos) e percentage (percentual em basis points). Retorna o objeto do desconto criado com status HTTP 201 Created.

​

Autenticação

Requer Organization Access Token (OAT) da organização pai via header Authorization: Bearer. A organização autenticada deve ser a organização pai da orgId informada.

​

Parâmetros de Path

orgId · string · required

Identificador único da sub-organização filha para a qual o desconto será criado.

​

Corpo da Requisição

name · string · required

Nome descritivo do desconto.

type · string · required

Tipo do desconto. Valores aceitos: fixed (valor fixo em centavos) ou percentage (percentual em basis points).

duration · string · required

Por quanto tempo o desconto é aplicado em assinaturas. Valores aceitos:

• once — aplicado apenas no primeiro pagamento
• forever — aplicado em todos os pagamentos
• repeating — aplicado por duration_in_months meses

basis_points · integer

Percentual do desconto em basis points. Obrigatório quando type é percentage. Ex: 1000 = 10%, 2000 = 20%, 500 = 5%.

amount · integer

Valor do desconto em centavos. Obrigatório quando type é fixed. Ex: 1000 = R$ 10,00.

currency · string

Moeda do desconto. Obrigatório quando type é fixed. Ex: brl.

code · string

Código de cupom para o cliente informar no checkout. Se omitido, o desconto é automático (sem cupom).

duration_in_months · integer

Número de meses de aplicação. Obrigatório quando duration é repeating.

max_redemptions · integer

Limite máximo de usos do desconto. null para uso ilimitado.

starts_at · string

Data de início de validade no formato ISO 8601. null para válido imediatamente.

ends_at · string

Data de expiração no formato ISO 8601. null para sem expiração.

products · array

Lista de IDs de produtos aos quais o desconto se aplica. Se omitido, aplica-se a todos os produtos.

user_metadata · object

Metadados customizados em formato chave-valor.

internal_reference · string

Referência interna para uso próprio da plataforma.

​

Resposta

Retorna o objeto do desconto criado com status 201 Created. Veja os campos em Listar Descontos.

​

Exemplos

​

Desconto percentual com cupom

cURL

curl -X POST "https://api.chargefy.io/api/v1/sdk/organizations/org_01j9abc333/discounts" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Desconto de Lançamento 20%",
    "type": "percentage",
    "duration": "once",
    "basis_points": 2000,
    "code": "LANCAMENTO20",
    "max_redemptions": 100,
    "ends_at": "2024-12-31T23:59:59Z"
  }'

​

Desconto fixo recorrente por 3 meses

cURL

curl -X POST "https://api.chargefy.io/api/v1/sdk/organizations/org_01j9abc333/discounts" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "R$10 off por 3 meses",
    "type": "fixed",
    "duration": "repeating",
    "duration_in_months": 3,
    "amount": 1000,
    "currency": "brl"
  }'

​

Resposta de Exemplo

{
  "id": "disc_01j9xyz111",
  "organization_id": "org_01j9abc333",
  "name": "Desconto de Lançamento 20%",
  "type": "percentage",
  "code": "LANCAMENTO20",
  "duration": "once",
  "duration_in_months": null,
  "basis_points": 2000,
  "max_redemptions": 100,
  "redemptions_count": 0,
  "starts_at": null,
  "ends_at": "2024-12-31T23:59:59Z",
  "created_at": "2024-10-15T10:00:00Z"
}