Cupons

Criar Cupom

Cria um cupom de desconto

POST

/v1/cupons

Escopo

cupons.escrever

Autorização

Authorizationstringobrigatórioheader

Chave da API no formato Bearer hdl_live_.... Crie no painel da loja em Integração › API e webhooks. Saiba mais.

Corpo da requisição

codigostringobrigatóriobody · application/json

3 a 40 letras, números, _ ou - (espaços são removidos, vira maiúsculas). Único na loja.

tipostringobrigatóriobody · application/json

porcentagem ou valor_fixo.

valornumberobrigatóriobody · application/json

Porcentagem (até 100) ou reais.

quantidade_disponivelintegerobrigatóriobody · application/json

Quantos usos.

validadestringobrigatóriobody · application/json

AAAA-MM-DD (vale até 23:59) ou ISO 8601.

nomestringbody · application/json

descricaostringbody · application/json

desconto_maximonumberbody · application/json

Teto em reais.

pedido_minimonumberbody · application/json

primeira_comprabooleanbody · application/json

frete_gratisbooleanbody · application/json

categoriasinteger[]body · application/json

Só nestas categorias.

limite_por_clienteintegerbody · application/json

Resposta

201 — objeto { "dados": {...} } com um Cupom.

Erros possíveis

HTTP	código	quando
`401`	`nao_autenticado`	Faltou o cabeçalho Authorization: Bearer <chave>.
`401`	`chave_invalida`	Chave inexistente ou revogada.
`403`	`sem_permissao`	A chave não tem o escopo exigido pelo endpoint.
`422`	`validacao`	Campos inválidos: veja o objeto "campos".

curl --request POST \ --url 'https://api.hoteldaslojas.com.br/v1/cupons' \ --header 'Authorization: Bearer <chave>' \ --header 'Content-Type: application/json' \ --data '{"codigo": "VOLTA15", "tipo": "porcentagem", "valor": 15, "quantidade_disponivel": 100, "validade": "2026-12-31", "pedido_minimo": 150}'

import os, requests resposta = requests.post( "https://api.hoteldaslojas.com.br/v1/cupons", headers={"Authorization": f"Bearer {os.environ['HDL_CHAVE']}"}, json={ "codigo": "VOLTA15", "tipo": "porcentagem", "valor": 15, "quantidade_disponivel": 100, "validade": "2026-12-31", "pedido_minimo": 150 }, timeout=30, ) resposta.raise_for_status() print(resposta.json()["dados"])

<?php $ch = curl_init('https://api.hoteldaslojas.com.br/v1/cupons'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('HDL_CHAVE'), 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'codigo' => 'VOLTA15', 'tipo' => 'porcentagem', 'valor' => 15, 'quantidade_disponivel' => 100, 'validade' => '2026-12-31', 'pedido_minimo' => 150 ]), ]); $resposta = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); print_r($resposta);

{ "dados": { "id": 381, "codigo": "VOLTA15", "nome": "VOLTA15", "descricao": "", "tipo": "porcentagem", "valor": 15.0, "desconto_maximo": null, "pedido_minimo": null, "quantidade_disponivel": 5, "validade": "2027-12-31T23:59:59-03:00", "primeira_compra": false, "frete_gratis": true, "categorias": [ 783 ], "limite_por_cliente": null } }

{ "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } }