---
title: "Detalhe do cupom"
description: "GET /v1/store/coupons/:couponId — detalhe de um cupom do restaurante."
method: "GET"
path: "/v1/store/coupons/{couponId}"
url: "https://developer.beefood.com.br/docs/loja/cupom"
group: "Restaurante"
scope: "coupons:read"
lang: "pt"
---
# Detalhe do cupom

`GET /v1/store/coupons/{couponId}`

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

Retorna o detalhe de um cupom.

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

- `couponId` *integer* **obrigatório** — ID do cupom. Exemplo: `15283`.





## Exemplos de requisição

### cURL

```bash
curl -X GET "https://api.beefood.app/v1/store/coupons/{couponId}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


## Exemplos de resposta

### Desconto percentual

```json
{
  "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": []
    }
  }
}
```

### Tipos de benefício · Desconto valor fixo

```json
{
  "couponId": 12249,
  "storeId": 38311,
  "merchantId": 39202,
  "code": "TESTEBEEFOOD",
  "active": false,
  "usageCount": 2,
  "benefit": {
    "appliesTo": "discount",
    "type": "fixed",
    "amount": 10
  },
  "validity": {
    "startsAt": "2026-02-25T19:18:45.847-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": "order",
      "sectors": [],
      "products": []
    }
  }
}
```

### Tipos de benefício · Frete valor fixo

```json
{
  "couponId": 13336,
  "storeId": 38311,
  "merchantId": 39202,
  "code": "FRETEGRATIS",
  "active": false,
  "usageCount": 2,
  "benefit": {
    "appliesTo": "deliveryFee",
    "type": "fixed",
    "amount": 0
  },
  "validity": {
    "startsAt": "2026-05-15T03:02:00.000-03:00",
    "weekdays": {
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": true,
      "friday": true,
      "saturday": true,
      "sunday": true
    }
  },
  "channels": {
    "delivery": true,
    "pdv": false,
    "tables": false,
    "totem": false
  },
  "rules": {
    "minimumOrderAmount": 0,
    "limitOnePerCustomer": false,
    "hasQuantityLimit": false,
    "maxQuantity": 0,
    "firstPurchaseOnly": false,
    "showOnMenu": true,
    "pickupOrLocalOnly": false,
    "excludePromotionalProducts": false,
    "requirePhoneSms": false
  },
  "advanced": {
    "paymentMethods": [],
    "application": {
      "mode": "order",
      "sectors": [],
      "products": []
    }
  }
}
```

### Tipos de benefício · Frete percentual

```json
{
  "couponId": 7516,
  "storeId": 1001,
  "merchantId": 2005,
  "code": "FRETE10",
  "active": false,
  "usageCount": 37,
  "benefit": {
    "appliesTo": "deliveryFee",
    "type": "percentage",
    "amount": 10
  },
  "validity": {
    "startsAt": "2024-12-30T12:13:00.000-03:00",
    "weekdays": {
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": true,
      "friday": true,
      "saturday": true,
      "sunday": true
    }
  },
  "channels": {
    "delivery": true,
    "pdv": false,
    "tables": false,
    "totem": false
  },
  "rules": {
    "minimumOrderAmount": 59.9,
    "limitOnePerCustomer": true,
    "hasQuantityLimit": false,
    "maxQuantity": 0,
    "firstPurchaseOnly": false,
    "showOnMenu": true,
    "pickupOrLocalOnly": false,
    "excludePromotionalProducts": false,
    "requirePhoneSms": false
  },
  "advanced": {
    "paymentMethods": [],
    "application": {
      "mode": "order",
      "sectors": [],
      "products": []
    }
  }
}
```

### Regras especiais · Primeira compra

```json
{
  "couponId": 15143,
  "storeId": 38311,
  "merchantId": 39202,
  "code": "FIRST",
  "active": true,
  "usageCount": 0,
  "benefit": {
    "appliesTo": "discount",
    "type": "percentage",
    "amount": 15
  },
  "validity": {
    "startsAt": "2026-08-21T03:54: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": true,
    "showOnMenu": true,
    "pickupOrLocalOnly": false,
    "excludePromotionalProducts": false,
    "requirePhoneSms": false
  },
  "advanced": {
    "paymentMethods": [],
    "application": {
      "mode": "itemsOnly",
      "sectors": [
        {
          "sectorId": 213752,
          "name": "Acompanhamentos"
        }
      ],
      "products": [
        {
          "productId": 2515342,
          "name": "Fatia de queijo"
        }
      ]
    }
  }
}
```

### Formas de aplicação · unlockByItems · Só quando o carrinho tiver certos itens

```json
{
  "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"
        }
      ]
    }
  }
}
```

### Formas de aplicação · itemsOnly · Só sobre certos itens do pedido

```json
{
  "couponId": 15231,
  "storeId": 38311,
  "merchantId": 39202,
  "code": "10%BEBIDA",
  "active": true,
  "usageCount": 0,
  "benefit": {
    "appliesTo": "discount",
    "type": "percentage",
    "amount": 10
  },
  "validity": {
    "startsAt": "2026-08-22T18:11: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": "itemsOnly",
      "sectors": [],
      "products": []
    }
  }
}
```


## Campos da resposta

- `couponId` *number* — ID do cupom a atualizar.

- `storeId` *number* — ID do restaurante.

- `merchantId` *number* — Cardápio em que o cupom vale.

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

- `active` *boolean* — Indica se o cupom está ativo.

- `usageCount` *number* — Quantas vezes já foi usado.

- `benefit.appliesTo` *string* — Sobre o que o benefício incide (pedido, frete ou produto).
  - *Valores:* `discount`, `deliveryFee`, `product`

- `benefit.type` *string* — Percentual ou valor fixo.
  - *Valores:* `percentage`, `fixed`

- `benefit.amount` *number* — Valor do benefício.

- `validity.startsAt` *string (ISO 8601)* — Início da validade; null remove a data de início.

- `validity.endsAt` *string (ISO 8601)* — Fim da validade; null remove a data de término (cupom sem data fim).

- `validity.weekdays` *object* — Dias da semana em que o cupom vale.

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

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

- `advanced.paymentMethods` *array* — Formas de pagamento que liberam o cupom; na atualização, a lista enviada substitui a atual (vazia = sem restrição).
  - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER`

- `advanced.paymentMethods[].paymentMethodId` *number* — ID da forma de pagamento.

- `advanced.paymentMethods[].name` *string* — Nome da forma de pagamento.

- `advanced.paymentMethods[].type` *string* — Tipo da forma de pagamento.
  - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER`

- `advanced.application` *object* — Como o cupom se aplica a setores/produtos; na atualização, sectors e products substituem as listas atuais.

- `advanced.application.mode` *string* — Modo de aplicação.
  - *Valores:* `order`, `unlockByItems`, `itemsOnly`

- `advanced.application.sectors` *array* — Setores relacionados ao cupom.

- `advanced.application.sectors[].sectorId` *number* — ID do setor.

- `advanced.application.sectors[].name` *string* — Nome do setor.

- `advanced.application.products` *array* — Produtos relacionados ao cupom.

- `advanced.application.products[].productId` *number* — ID do produto.

- `advanced.application.products[].name` *string* — Nome do produto.

- `channels.delivery` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo delivery.

- `channels.pdv` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo PDV.

- `channels.tables` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo mesa.

- `channels.totem` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo totem.

- `rules.minimumOrderAmount` *number* — Valor mínimo do pedido; null remove o pedido mínimo.

- `rules.limitOnePerCustomer` *boolean* — Limita a 1 uso por cliente.

- `rules.hasQuantityLimit` *boolean* — Indica se há limite total de usos.

- `rules.maxQuantity` *number* — Quantidade máxima de usos; null remove o teto (use junto com hasQuantityLimit: false).

- `rules.firstPurchaseOnly` *boolean* — Só na primeira compra.

- `rules.showOnMenu` *boolean* — Exibe o cupom no cardápio.

- `rules.pickupOrLocalOnly` *boolean* — Só para retirada ou presencial.

- `rules.excludePromotionalProducts` *boolean* — Não aplica em produtos em promoção.

- `rules.requirePhoneSms` *boolean* — Exige validação de telefone por SMS.



## Erros

| Status | Mensagem |
| --- | --- |
| 401 | Authentication token is missing |
| 401 | Invalid or expired access token |
| 403 | This credential does not include the coupons:read scope |
| 404 | Coupon ID 99 not found |


## Vocabulários usados neste endpoint

## Pagamento · method.type

Mesmo vocabulário usado no bloco payments do pedido e nas formas de pagamento permitidas em cupons.

| Valor | Significado | Uso |
| --- | --- | --- |
| `CASH` | Dinheiro | Pedidos e cupons |
| `CREDIT_CARD` | Cartão de crédito | Pedidos e cupons |
| `DEBIT_CARD` | Cartão de débito | Pedidos e cupons |
| `PIX_BEEFOOD` | Pix BeeFood | Pedidos e cupons |
| `FOOD_VOUCHER` | Vale-alimentação | Pedidos e cupons |
| `MEAL_VOUCHER` | Vale-refeição | Pedidos e cupons |
| `DIGITAL_WALLET` | Carteira digital | Pedidos e cupons |
| `STORE_CREDIT` | Crédito no restaurante | Pedidos e cupons |
| `OTHER` | Outro | Pedidos e cupons |

## Cupons · benefit.type

| Valor | Significado | Uso |
| --- | --- | --- |
| `percentage` | Percentual | Cupons |
| `fixed` | Valor fixo | Cupons |

## Cupons · benefit.appliesTo

| Valor | Significado | Uso |
| --- | --- | --- |
| `discount` | Desconto no pedido | Cupons |
| `deliveryFee` | Taxa de entrega | Cupons |
| `product` | Produto | Cupons |

## Cupons · advanced.application.mode

| Valor | Significado | Uso |
| --- | --- | --- |
| `order` | Ao pedido inteiro (padrão) | sectors e products devem ser [] |
| `unlockByItems` | Só quando o carrinho tiver certos itens | Exige ao menos um setor ou produto |
| `itemsOnly` | Só sobre certos itens do pedido | Exige itens e appliesTo: discount |

## Cupons · channels

Cada canal é um booleano.

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