Pular para o conteúdo principal
POST
/
api
/
partner
/
v1
/
merchant
/
coupons
Criar cupom
curl --request POST \
  --url https://integracao.sandbox.cardapioweb.com/api/partner/v1/merchant/coupons \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "name": "<string>",
  "type": "percent_discount",
  "value": 123,
  "code": null,
  "active": true,
  "minimum_order_value": null,
  "use_limit": null,
  "new_customers_only": false,
  "customer_multi_use": false,
  "availability_start_time": null,
  "availability_end_time": null,
  "available_days": [],
  "available_order_types": [],
  "available_from": null,
  "expires_at": null,
  "item_ids": [
    123
  ]
}
'
{
  "name": "<string>",
  "type": "percent_discount",
  "value": 123,
  "id": 123,
  "uid": "<string>",
  "code": null,
  "active": true,
  "minimum_order_value": null,
  "use_limit": null,
  "new_customers_only": false,
  "customer_multi_use": false,
  "availability_start_time": null,
  "availability_end_time": null,
  "available_days": [],
  "available_order_types": [],
  "available_from": null,
  "expires_at": null,
  "item_ids": [
    {
      "id": 123,
      "name": "<string>"
    }
  ]
}

Autorizações

​
X-API-KEY
string
header
obrigatório

Token específico do estabelecimento integrado. Disponível na seção de integrações do Portal do estabelecimento.

Corpo

application/json

Estrutura do cupom

​
name
string
obrigatório

Nome do cupom. Essa informação fica vísivel para o cliente.

​
type
enum<string>
obrigatório

Tipo de cupom:

  • free_shipping: Entrega grátis.
  • percent_discount: Desconto percentual no carrinho.
  • flat_discount: Desconto fixo no carrinho.
Opções disponíveis:
free_shipping,
percent_discount,
flat_discount
Exemplo:

"percent_discount"

​
value
number | null
obrigatório

Valor do desconto:

  • Para type igual a free_shipping, esse campo será null.
  • Para percent_discount, deve ser maior que 0 e menor ou igual a 100.
  • Para flat_discount, deve ser maior que 0.
​
code
string | null

Código do Cupom. Nos cupons com código, o cliente deve informar o código durante a compra. Cupons sem código são visíveis e disponíveis para todos os clientes.

​
active
boolean
padrão:true

Indica se o cupom está ativo.

​
minimum_order_value
number | null

Valor mínimo do pedido que o cliente precisa alcançar para poder usar o cupom.

​
use_limit
integer | null

Indica o número máximo de vezes que o cupom pode ser usado.

​
new_customers_only
boolean
padrão:false

Indica se o cupom é válido apenas para novos clientes.

​
customer_multi_use
boolean
padrão:false

Indica se um cliente pode usar o cupom mais de uma vez.

​
availability_start_time
string<time> | null

Define o horário a partir do qual o cupom estará disponível para uso. Segue o formato de 24 horas, indo de 00:00 a 23:59. Não inclui os segundos.

​
availability_end_time
string<time> | null

Define o horário até o qual o cupom estará disponível para uso. Segue o formato de 24 horas, indo de 00:00 a 23:59. Não inclui os segundos.

​
available_days
enum<string>[]

Especifique os dias da semana em que o cupom pode ser usado. Por padrão, o cupom é válido todos os dias da semana. Se o array estiver vazio, isso significa que o cupom está disponível todos os dias.

Required array length: 1 - 7 elements
Opções disponíveis:
sunday,
monday,
tuesday,
wednesday,
thursday,
friday,
saturday
​
available_order_types
enum<string>[]

Disponibilidade do cupom por tipo de pedido:

  • delivery: disponível em pedidos de delivery.
  • takeout: disponível em pedidos de retirada.
  • onsite: disponível em pedidos de consumo no local. Por padrão, o cupom fica disponível todos os tipos de pedido. Se o array estiver vazio, isso significa que o cupom está disponível para todos os tipos de pedidos.
Required array length: 1 - 3 elements
Opções disponíveis:
delivery,
takeout,
onsite
​
available_from
string<date> | null

Data a partir da qual o cupom está disponível para uso, iniciando à meia-noite (00:00) do dia indicado, no formato YYYY-MM-DD.

​
expires_at
string<date> | null

Data em que o cupom expira e não pode mais ser usado. O cupom é válido até 23:59 do dia especificado. Formato YYYY-MM-DD.

​
item_ids
integer[]

ID dos produtos aos quais o desconto será aplicado. Essa opção está disponível apenas quando type for igual a percent_discount.

Maximum array length: 30

Resposta

Cupom criado com sucesso!

Estrutura do cupom

​
name
string
obrigatório

Nome do cupom. Essa informação fica vísivel para o cliente.

​
type
enum<string>
obrigatório

Tipo de cupom:

  • free_shipping: Entrega grátis.
  • percent_discount: Desconto percentual no carrinho.
  • flat_discount: Desconto fixo no carrinho.
Opções disponíveis:
free_shipping,
percent_discount,
flat_discount
Exemplo:

"percent_discount"

​
value
number | null
obrigatório

Valor do desconto:

  • Para type igual a free_shipping, esse campo será null.
  • Para percent_discount, deve ser maior que 0 e menor ou igual a 100.
  • Para flat_discount, deve ser maior que 0.
​
id
integer
read-only

ID único do cupom

​
uid
string
read-only

Identificador alfanumérico único do cupom, utilizado para a aplicação automática no site. Deve ser usado da seguinte forma: https://app.sandbox.cardapioweb.com/teste_integracao?cid={uid}

​
code
string | null

Código do Cupom. Nos cupons com código, o cliente deve informar o código durante a compra. Cupons sem código são visíveis e disponíveis para todos os clientes.

​
active
boolean
padrão:true

Indica se o cupom está ativo.

​
status
enum<string>
read-only

Status do cupom:

  • not_active: O cupom está inativo e não pode ser usado no momento.
  • not_yet_available: O cupom ainda não está disponível para uso. Ver campo available_from.
  • expired: O cupom expirou e não pode mais ser utilizado. Ver campo expires_at.
  • usage_limit_reached: O cupom atingiu o limite de uso permitido e não está mais disponível. Ver campo use_limit.
  • not_available: O cupom não está disponível no momento. Ver campos availability_start_time, availability_end_time e available_days.
  • valid: O cupom está ativo e pode ser utilizado.
Opções disponíveis:
not_active,
not_yet_available,
expired,
usage_limit_reached,
not_available,
valid
​
minimum_order_value
number | null

Valor mínimo do pedido que o cliente precisa alcançar para poder usar o cupom.

​
use_limit
integer | null

Indica o número máximo de vezes que o cupom pode ser usado.

​
new_customers_only
boolean
padrão:false

Indica se o cupom é válido apenas para novos clientes.

​
customer_multi_use
boolean
padrão:false

Indica se um cliente pode usar o cupom mais de uma vez.

​
availability_start_time
string<time> | null

Define o horário a partir do qual o cupom estará disponível para uso. Segue o formato de 24 horas, indo de 00:00 a 23:59. Não inclui os segundos.

​
availability_end_time
string<time> | null

Define o horário até o qual o cupom estará disponível para uso. Segue o formato de 24 horas, indo de 00:00 a 23:59. Não inclui os segundos.

​
available_days
enum<string>[]

Especifique os dias da semana em que o cupom pode ser usado. Por padrão, o cupom é válido todos os dias da semana. Se o array estiver vazio, isso significa que o cupom está disponível todos os dias.

Required array length: 1 - 7 elements
Opções disponíveis:
sunday,
monday,
tuesday,
wednesday,
thursday,
friday,
saturday
​
available_order_types
enum<string>[]

Disponibilidade do cupom por tipo de pedido:

  • delivery: disponível em pedidos de delivery.
  • takeout: disponível em pedidos de retirada.
  • onsite: disponível em pedidos de consumo no local. Por padrão, o cupom fica disponível todos os tipos de pedido. Se o array estiver vazio, isso significa que o cupom está disponível para todos os tipos de pedidos.
Required array length: 1 - 3 elements
Opções disponíveis:
delivery,
takeout,
onsite
​
available_from
string<date> | null

Data a partir da qual o cupom está disponível para uso, iniciando à meia-noite (00:00) do dia indicado, no formato YYYY-MM-DD.

​
expires_at
string<date> | null

Data em que o cupom expira e não pode mais ser usado. O cupom é válido até 23:59 do dia especificado. Formato YYYY-MM-DD.

​
item_ids
object[]

Produtos aos quais o desconto será aplicado. Essa opção está disponível apenas quando type for igual a percent_discount.

Maximum array length: 30
Última modificação em 27 de junho de 2026