> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bukiopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Cria um cupom de desconto percentual ou de valor fixo na loja, com código único, limite de usos e data de expiração configuráveis.

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

<ParamField body="code" type="string" required>
  Código do cupom que será digitado pelo cliente no checkout (ex: `DESCONTO20`). Deve ser único na loja.
</ParamField>

<ParamField body="type" type="string" required>
  Tipo do desconto. Use `percentage` para desconto em porcentagem ou `fixed` para desconto de valor fixo em reais.
</ParamField>

<ParamField body="value" type="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).
</ParamField>

<ParamField body="maxUses" type="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.
</ParamField>

<ParamField body="expiresAt" type="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.
</ParamField>

## Exemplo de Requisição

```bash theme={null}
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

```json theme={null}
{
  "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

<ResponseField name="message" type="string">
  Mensagem de confirmação da operação.
</ResponseField>

<ResponseField name="coupon" type="object">
  Objeto com os dados do cupom recém-criado.

  <Expandable title="Propriedades do cupom">
    <ResponseField name="id" type="string">
      Identificador único gerado automaticamente para o novo cupom.
    </ResponseField>

    <ResponseField name="code" type="string">
      Código do cupom conforme informado na requisição.
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo do desconto: `percentage` ou `fixed`.
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor do desconto conforme informado na requisição.
    </ResponseField>

    <ResponseField name="maxUses" type="number">
      Limite máximo de utilizações do cupom.
    </ResponseField>

    <ResponseField name="usedCount" type="number">
      Contador de utilizações. Sempre inicia em `0` após a criação.
    </ResponseField>

    <ResponseField name="active" type="boolean">
      Status do cupom. Sempre `true` após a criação.
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      Data e hora de expiração no formato ISO 8601.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Data e hora de criação do cupom no formato ISO 8601.
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.