> ## 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.

# GET /api/v1/coupons: Listar Todos os Cupons da Loja

> Lista todos os cupons de desconto da loja com código, tipo (percentage ou fixed), valor, limite de uso, contagem de usos e data de expiração.

Use este endpoint para recuperar todos os cupons de desconto cadastrados na sua loja. A resposta inclui informações completas de cada cupom, como código, tipo de desconto, valor, quantidade de usos já realizados, limite máximo de usos e data de expiração.

## Método

`GET /api/v1/coupons` — Requer autenticação.

## Exemplo de Requisição

```bash theme={null}
curl -X GET 'https://api.bukiopay.com/api/v1/coupons' \
  --header 'Authorization: Bearer sk_live_sua_api_key'
```

## Resposta

```json theme={null}
{
  "coupons": [
    {
      "id": "cpn_123",
      "code": "DESCONTO10",
      "type": "percentage",
      "value": 10,
      "maxUses": 100,
      "usedCount": 25,
      "active": true,
      "expiresAt": "2026-12-31T23:59:59.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}
```

## Campos da Resposta

<ResponseField name="coupons" type="array">
  Lista de cupons de desconto da loja autenticada.

  <Expandable title="Propriedades de cada cupom">
    <ResponseField name="id" type="string">
      Identificador único do cupom.
    </ResponseField>

    <ResponseField name="code" type="string">
      Código do cupom que o cliente insere no checkout (ex: `DESCONTO10`).
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo do desconto. Os valores possíveis são:

      * `percentage` — desconto em porcentagem sobre o valor total do pedido.
      * `fixed` — desconto de valor fixo em reais (R\$).
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor do desconto. Para `percentage`, representa a porcentagem (ex: `10` = 10%). Para `fixed`, representa o valor em reais (ex: `15` = R\$ 15,00).
    </ResponseField>

    <ResponseField name="maxUses" type="number">
      Número máximo de vezes que o cupom pode ser utilizado. `null` indica sem limite.
    </ResponseField>

    <ResponseField name="usedCount" type="number">
      Quantidade de vezes que o cupom já foi utilizado.
    </ResponseField>

    <ResponseField name="active" type="boolean">
      Indica se o cupom está ativo e disponível para uso.
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      Data e hora de expiração do cupom no formato ISO 8601. `null` indica sem data de expiração.
    </ResponseField>

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

<Note>
  O campo `type` define como o desconto é calculado: `percentage` aplica uma porcentagem sobre o total do pedido, enquanto `fixed` subtrai um valor fixo em reais. Use o endpoint de [validação de cupom](/api-reference/coupons/validate) para calcular o desconto real antes de aplicá-lo ao checkout.
</Note>


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