POST /api/v1/coupons: Criar Novo Cupom de Desconto

Use este endpoint para criar um novo cupom de desconto na sua loja. Você pode configurar descontos percentuais ou de valor fixo, definir um limite máximo de usos e uma data de expiração para controlar a validade da promoção.

Método

POST /api/v1/coupons — Requer autenticação.

Parâmetros do Body

string

required

Código do cupom que será digitado pelo cliente no checkout (ex: DESCONTO20). Deve ser único na loja.

string

required

Tipo do desconto. Use percentage para desconto em porcentagem ou fixed para desconto de valor fixo em reais.

number

required

Valor do desconto. Para percentage, informe a porcentagem (ex: 20 = 20% de desconto). Para fixed, informe o valor em reais (ex: 15 = R$ 15,00 de desconto).

number

Limite máximo de utilizações do cupom. Após atingir esse número, o cupom será automaticamente inativado. Deixe em branco para cupom sem limite de uso.

string

Data e hora de expiração do cupom no formato ISO 8601 (ex: 2026-12-31T23:59:59.000Z). Após essa data, o cupom não poderá mais ser utilizado. Deixe em branco para cupom sem validade.

Exemplo de Requisição

curl -X POST 'https://api.bukiopay.com/api/v1/coupons' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "DESCONTO20",
    "type": "percentage",
    "value": 20,
    "maxUses": 50,
    "expiresAt": "2026-12-31T23:59:59.000Z"
  }'

Resposta

{
  "message": "Cupom criado com sucesso",
  "coupon": {
    "id": "cpn_456",
    "code": "DESCONTO20",
    "type": "percentage",
    "value": 20,
    "maxUses": 50,
    "usedCount": 0,
    "active": true,
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "createdAt": "2026-05-07T10:00:00.000Z"
  }
}

Campos da Resposta

string

Mensagem de confirmação da operação.

object

Objeto com os dados do cupom recém-criado.

Show Propriedades do cupom

string

Identificador único gerado automaticamente para o novo cupom.

string

Código do cupom conforme informado na requisição.

string

Tipo do desconto: percentage ou fixed.

number

Valor do desconto conforme informado na requisição.

number

Limite máximo de utilizações do cupom.

number

Contador de utilizações. Sempre inicia em 0 após a criação.

boolean

Status do cupom. Sempre true após a criação.

string

Data e hora de expiração no formato ISO 8601.

string

Data e hora de criação do cupom no formato ISO 8601.

Introdução à API

Cobranças PIX

Saques

Webhooks

Pedidos

Produtos

Categorias

Cupons

Loja

POST /api/v1/coupons: Criar Novo Cupom de Desconto

Método

Parâmetros do Body

Exemplo de Requisição

Resposta

Campos da Resposta

​Método

​Parâmetros do Body

​Exemplo de Requisição

​Resposta

​Campos da Resposta

Método

Parâmetros do Body

Exemplo de Requisição

Resposta

Campos da Resposta