--- title: "Atualizar cupom" description: "PATCH /v1/store/coupons/:couponId — atualização parcial de cupons." method: "PATCH" path: "/v1/store/coupons/{couponId}" url: "https://developer.beefood.com.br/docs/loja/atualizar-cupom" group: "Restaurante" scope: "coupons:write" lang: "pt" --- # Atualizar cupom `PATCH /v1/store/coupons/{couponId}` - Produção: `https://api.beefood.app/v1/store/coupons/{couponId}` - Sandbox: `https://api-sandbox.beefood.app/v1/store/coupons/{couponId}` Atualiza parcialmente um cupom da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `coupons:write`. Limite: 100 requisições a cada 3 minutos. ## Observações - Os campos não enviados terão seu valor preservado; apenas os campos enviados (ou enviados como null) serão alterados. ## Parâmetros de path - `couponId` *integer* **obrigatório** — ID do cupom a atualizar. Exemplo: `15283`. ## Parâmetros do body - `active` *boolean* — Indica se o cupom está ativo. - `code` *string* — Código para a utilização do cupom. - `benefit` *object* — Benefício concedido pelo cupom; na atualização, faz merge campo a campo (envie só o que mudar). - `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` *object* — Período e dias em que o cupom vale; na atualização, faz merge campo a campo. - `validity.startsAt` *string (ISO 8601) | null* — Início da validade; null remove a data de início. - `validity.endsAt` *string (ISO 8601) | null* — 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. - `rules.minimumOrderAmount` *number | null* — 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 | null* — 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. - `advanced` *object* — Restrições avançadas 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. - `advanced.paymentMethods[].type` *string* — Tipo da forma. - *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: order, unlockByItems ou itemsOnly. - *Valores:* `order`, `unlockByItems`, `itemsOnly` - `advanced.application.sectors` *array* — Setores relacionados; a lista enviada substitui a atual. - `advanced.application.sectors[].sectorId` *number* — ID do setor (obrigatório no envio). - `advanced.application.products` *array* — Produtos relacionados; a lista enviada substitui a atual. - `advanced.application.products[].productId` *number* — ID do produto (obrigatório no envio). ## Exemplos de body ### Atualizações pontuais · Desativar o cupom ```json { "active": false } ``` ### Atualizações pontuais · Mudar o valor do benefício ```json { "benefit": { "amount": 20 } } ``` ### Atualizações pontuais · Remover a data de término ```json { "validity": { "endsAt": null } } ``` ### Atualizações pontuais · Remover o pedido mínimo ```json { "rules": { "minimumOrderAmount": null } } ``` ### Atualizações pontuais · Remover o limite de quantidade ```json { "rules": { "hasQuantityLimit": false, "maxQuantity": null } } ``` ### Atualizações pontuais · Alterar só a quinta-feira ```json { "validity": { "weekdays": { "thursday": true } } } ``` ### Atualizações pontuais · Aceitar todas as formas de pagamento ```json { "advanced": { "paymentMethods": [] } } ``` ### Formas de aplicação · order · Ao pedido inteiro (padrão) ```json { "advanced": { "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Formas de aplicação · unlockByItems · Só quando o carrinho tiver certos itens ```json { "advanced": { "application": { "mode": "unlockByItems", "sectors": [ { "sectorId": 45 } ], "products": [ { "productId": 1234 }, { "productId": 5678 } ] } } } ``` ### Formas de aplicação · itemsOnly · Só sobre certos itens do pedido ```json { "benefit": { "appliesTo": "discount" }, "advanced": { "application": { "mode": "itemsOnly", "sectors": [], "products": [ { "productId": 1234 } ] } } } ``` ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/store/coupons/{couponId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "benefit": { "amount": 20 } }' ``` ## Exemplos de resposta ### 200 OK ```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": [] } } } ``` ### Formas de aplicação · order · Ao pedido inteiro (padrão) ```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 · unlockByItems · Só quando o carrinho tiver certos itens ```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 | | --- | --- | | 400 | body must include at least one field | | 400 | 'benefit' must include at least one field | | 400 | 'merchantId' is not allowed | | 400 | 'extra' is not allowed | | 400 | 'benefit.type' must be one of percentage, fixed | | 400 | 'validity.startsAt' must be an ISO 8601 date-time | | 400 | rules.maxQuantity must be >= 1 when rules.hasQuantityLimit is true | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the coupons:write 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 |