---
title: "Listar cupons"
description: "GET /v1/store/coupons — cupons de desconto do restaurante BeeFood."
method: "GET"
path: "/v1/store/coupons"
url: "https://developer.beefood.com.br/docs/loja/cupons"
group: "Restaurante"
scope: "coupons:read"
lang: "pt"
---
# Listar cupons

`GET /v1/store/coupons`

- Produção: `https://api.beefood.app/v1/store/coupons`
- Sandbox: `https://api-sandbox.beefood.app/v1/store/coupons`

Retorna os cupons da empresa.

## Autenticação

Envie o access token no header `Authorization: Bearer <accessToken>`. Escopo necessário: `coupons:read`. Limite: 100 requisições a cada 3 minutos.



## Parâmetros de query

- `page` *integer* — Página atual da lista. Exemplo: `1`.

- `limit` *integer* — Quantidade de itens por página. Exemplo: `20`.

- `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`.
  - *Valores:* `asc`, `desc`

- `merchantId` *integer* — Filtra por cardápio. Exemplo: `1`.

- `code` *string* — Filtra pelo código digitado pelo cliente. Exemplo: `"PIX15%"`.

- `active` *boolean* — Filtra por cupons ativos ou inativos. Ausente = todos. Exemplo: `true`.

- `type` *string* — Filtra pelo tipo do benefício: percentage ou fixed. Exemplo: `"percentage"`.

- `appliesTo` *string* — Filtra pelo alvo do benefício: discount, deliveryFee ou product. Exemplo: `"discount"`.

- `validFrom` *string (ISO 8601)* — Filtra pelos cupons vigentes a partir dessa data. Exemplo: `"2026-03-01T00:00:00-03:00"`.

- `validUntil` *string (ISO 8601)* — Filtra pelos cupons vigentes até essa data. Exemplo: `"2026-03-31T23:59:59-03:00"`.

- `paymentMethodType` *string* — Filtra pelos cupons restritos a uma forma de pagamento listada em advanced.paymentMethods. Exemplo: `"PIX_BEEFOOD"`.

- `applicationMode` *string* — Filtra pelo modo de aplicação: order, unlockByItems ou itemsOnly. Exemplo: `"order"`.




## Exemplos de requisição

### cURL

```bash
curl -X GET "https://api.beefood.app/v1/store/coupons?page=1&limit=20&sort=desc" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


## Exemplos de resposta

### 200 OK

```json
{
  "items": [
    {
      "couponId": 15237,
      "storeId": 38311,
      "merchantId": 39202,
      "code": "PIX15%",
      "active": true,
      "usageCount": 0,
      "benefit": {
        "appliesTo": "discount",
        "type": "percentage",
        "amount": 15
      },
      "validity": {
        "startsAt": "2026-08-22T23:34:00.000-03:00",
        "weekdays": {
          "monday": true,
          "tuesday": true,
          "wednesday": true,
          "thursday": true,
          "friday": true,
          "saturday": true,
          "sunday": true
        }
      },
      "channels": {
        "delivery": true,
        "pdv": true,
        "tables": true,
        "totem": true
      },
      "rules": {
        "minimumOrderAmount": 0,
        "limitOnePerCustomer": false,
        "hasQuantityLimit": false,
        "maxQuantity": 0,
        "firstPurchaseOnly": false,
        "showOnMenu": true,
        "pickupOrLocalOnly": false,
        "excludePromotionalProducts": false,
        "requirePhoneSms": true
      },
      "advanced": {
        "paymentMethods": [
          {
            "paymentMethodId": 486229,
            "name": "PIX Bee",
            "type": "PIX_BEEFOOD"
          },
          {
            "paymentMethodId": 381233,
            "name": "PIX Online",
            "type": "PIX_BEEFOOD"
          }
        ],
        "application": {
          "mode": "order",
          "sectors": [],
          "products": []
        }
      }
    },
    {
      "couponId": 15233,
      "storeId": 38311,
      "merchantId": 39202,
      "code": "10%SETIVERBOX",
      "active": true,
      "usageCount": 0,
      "benefit": {
        "appliesTo": "discount",
        "type": "percentage",
        "amount": 10
      },
      "validity": {
        "startsAt": "2026-08-23T13:14:00.000-03:00",
        "weekdays": {
          "monday": true,
          "tuesday": true,
          "wednesday": true,
          "thursday": true,
          "friday": true,
          "saturday": true,
          "sunday": true
        }
      },
      "channels": {
        "delivery": true,
        "pdv": true,
        "tables": true,
        "totem": true
      },
      "rules": {
        "minimumOrderAmount": 0,
        "limitOnePerCustomer": false,
        "hasQuantityLimit": false,
        "maxQuantity": 0,
        "firstPurchaseOnly": false,
        "showOnMenu": true,
        "pickupOrLocalOnly": false,
        "excludePromotionalProducts": false,
        "requirePhoneSms": false
      },
      "advanced": {
        "paymentMethods": [],
        "application": {
          "mode": "unlockByItems",
          "sectors": [],
          "products": [
            {
              "productId": 2515304,
              "name": "(Box) Batata frita"
            }
          ]
        }
      }
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 13,
  "pages": 7
}
```


## Campos da resposta

- `items[].couponId` *number* — ID do cupom.

- `items[].code` *string* — Código para a utilização do cupom.

- `items[].benefit` *object* — Benefício concedido pelo cupom.

- `items[].validity` *object* — Período e dias em que o cupom vale.

- `items[].channels` *object* — Canais em que o cupom vale.
  - *Valores:* `delivery`, `pdv`, `tables`, `totem`

- `items[].rules` *object* — Regras de uso do cupom.

- `items[].advanced` *object* — Restrições avançadas do cupom.

- `page` *number* — Página atual da lista.

- `limit` *number* — Quantidade de itens por página.

- `total` *number* — Total de registros encontrados.

- `pages` *number* — Total de páginas.



## Erros

| Status | Mensagem |
| --- | --- |
| 400 | 'page' must be an integer >= 1 |
| 400 | 'limit' must be an integer between 1 and 100 |
| 400 | 'sort' must be asc or desc |
| 401 | Authentication token is missing |
| 401 | Invalid or expired access token |
| 403 | This credential does not include the coupons:read scope |
| 500 | Database error when trying to … |


## Vocabulários usados neste endpoint

## Cupons · channels

Cada canal é um booleano.

| Valor | Significado | Uso |
| --- | --- | --- |
| `delivery` | Delivery | Cupons |
| `pdv` | PDV | Cupons |
| `tables` | Mesas | Cupons |
| `totem` | Totem | Cupons |

## Listagens · sort

| Valor | Significado | Uso |
| --- | --- | --- |
| `asc` | Crescente | Todas as listagens |
| `desc` | Decrescente (padrão) | Todas as listagens |