API: Módulo Cupons (coupons)

O módulo coupons leva os cupons de desconto da loja para a API. Dá para listar, consultar, criar e atualizar cupons com as mesmas regras da aba Cupons do painel: desconto em valor ou percentual, frete grátis, limites de uso, validade, escopo por categoria ou produto e público restrito por conta ou por CPF/CNPJ. É ótimo para CRM, automação de marketing, programas de indicação e campanhas com parceiros ou influenciadores, em que cada um ganha o seu código sem ninguém precisar cadastrar cupom por cupom.

⚠️ A API precisa estar habilitada para utilizá-la. Veja o passo a passo em API - Como habilitar.

Endpoint: https://app.interago.com.br/App/Api/index.php

Todas as chamadas são POST com:

• Cabeçalho Authorization: Bearer SEU_TOKEN
• websiteId no corpo
• module=coupons e method com o nome do método

Limite: 60 requisições autenticadas por minuto por website, além da cota do mês explicada em API - Como habilitar. Trate o token como senha.

Antes de começar

• A extensão de cupons precisa estar instalada no site. No painel, ela é a extensão Promoções, com a aba Cupons (Menu → Extensões → Promoções). Sem ela, a API responde 403 COUPONS_EXTENSION_REQUIRED.

• No painel, abra API Interago e clique no chip Cupons. Ali ficam o testador e a descrição dos 5 métodos do módulo. O chip fica disponível quando a extensão de cupons está instalada.

• Consultas (listCoupons, getCoupon e checkCouponCode) funcionam em qualquer plano. Criar e atualizar (createCoupon e updateCoupon) exige plano pago: loja do plano grátis recebe 403 FREE_TIER_DENIED.

• O cupom criado ou alterado pela API é o mesmo cupom da aba Cupons: aparece na lista do painel, pode ser editado por lá e vale no carrinho e no checkout com as mesmas regras.

• Não existe método para apagar cupom. Para encerrar uma campanha antes da hora, use updateCoupon e traga o endDate para agora (tem exemplo mais abaixo).

Os 5 métodos

Campos do cupom

Valem para createCoupon e updateCoupon. Entre parênteses, o nome do campo na tela do painel, quando existe.

• code: o código que o cliente digita (Código do CUPOM). Opcional na criação: de 3 a 40 caracteres, com letras, números, _ ou -, começando por letra ou número. Em branco, a API gera um código de 6 caracteres. Depois de criado, não muda.
• name e description: textos internos de controle (Nome do Cupom e Descrição do Cupom), até 255 caracteres cada.
• discountType (obrigatório): percent para percentual ou value para valor fixo em reais.
• discountValue (obrigatório): o desconto. Prefira número com ponto, por exemplo 10 ou 15.5, sem máscara de R$. No percentual, precisa ser maior que 0 e no máximo 100. No valor fixo, precisa ser maior que 0, a não ser que o cupom seja só de frete grátis (discountValue=0 com freeShipping=1).
• freeShipping: 1 dá frete grátis com o cupom; 0 (padrão) não dá.
• useLimit (obrigatório): quantas vezes o cupom pode ser usado no total, no mínimo 1.
• useLimitPerPerson (obrigatório): quantas vezes cada cliente pode usar, no mínimo 1.
• limitByDocument: 1 conta o limite por cliente pelo CPF/CNPJ, e não só pela conta logada, como a opção equivalente do painel.
• startDate e endDate (obrigatórios): início e fim da validade (Início da Validade e Fim da Validade), no formato AAAA-MM-DD HH:MM:SS. Só a data também vale e vira meia-noite. O fim precisa ser depois do início.
• scope: onde o cupom vale. all (padrão) para a loja inteira, category para categorias ou product para produtos.
• scopeIds: ids das categorias ou dos produtos, separados por vírgula. Obrigatório quando scope é category ou product, com até 100 ids, e todos precisam existir na loja.

Público: loja inteira ou clientes escolhidos

• Sem accountIds e sem includeDocuments (ou com accountIds=all), o cupom vale para qualquer cliente da loja.
• accountIds: ids das contas de clientes da loja que podem usar o cupom, separados por vírgula, até 100. O CPF/CNPJ de cada conta entra sozinho na lista de documentos liberados, do mesmo jeito que no painel.
• includeDocuments: CPF ou CNPJ liberados, separados por ponto e vírgula (ou em uma lista JSON), até 200. Pode enviar só os números ou usar os prefixos cpf: e cnpj:. Não combine com accountIds=all: a API recusa com AUDIENCE_CONFLICT.
• excludeDocuments: CPF ou CNPJ que não podem usar o cupom, no mesmo formato, até 200.
• Todo documento é validado antes de gravar. Nas respostas, as listas voltam sempre mascaradas: aparece o tipo (cpf ou cnpj) e o documento oculto, nunca o número completo.

Listar e consultar

• listCoupons: status aceita active (valendo agora), scheduled (a iniciar), expired (expirados) e all (padrão), os mesmos filtros da aba Cupons. code filtra por parte do código.
• Paginação: page começa em 1 e pageSize tem padrão e máximo de 50. Enquanto a resposta trouxer hasMore: true, peça a próxima página.
• Cada cupom da lista traz couponId, code, tipo e valor do desconto, frete grátis, limites, datas, status, escopo e audience (all para a loja inteira ou restricted para público restrito).
• getCoupon: informe couponId ou code, nunca os dois. Além das regras, devolve accountIds, as listas de documentos mascaradas, usageCount (total de usos) e uses, com os últimos 50 usos (data, pedido e conta). Ótimo para medir quantos pedidos a campanha gerou.
• checkCouponCode: com code obrigatório, responde available: true quando o código está livre. Use antes de criar para evitar o 409 COUPON_CODE_EXISTS.

Atualizar sem surpresa

• couponId é obrigatório. Envie só o que vai mudar: o que você não mandar continua como está.
• O code não muda. Tentar trocar devolve COUPON_CODE_IMMUTABLE; para outro código, crie outro cupom.
• Para mudar o scope para category ou product, envie também scopeIds. Com scope=all, o cupom volta a valer para a loja inteira.
• includeDocuments e excludeDocuments substituem a lista inteira: envie a lista completa, não só o documento novo.
• Sem nenhum campo para alterar, a API responde NO_FIELDS.

Exemplos em curl

Conferir se o código está livre:

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=coupons' \ -d 'method=checkCouponCode' \ -d 'code=BEMVINDO10'

Criar um cupom de 10% na loja inteira, com um uso por cliente contado pelo CPF/CNPJ:

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=coupons' \ -d 'method=createCoupon' \ -d 'code=BEMVINDO10' \ --data-urlencode 'name=Boas-vindas 10%' \ -d 'discountType=percent' -d 'discountValue=10' \ -d 'useLimit=500' -d 'useLimitPerPerson=1' -d 'limitByDocument=1' \ --data-urlencode 'startDate=2026-11-01 00:00:00' \ --data-urlencode 'endDate=2026-11-30 23:59:59'

Criar um cupom de R$ 15 que vale só em duas categorias:

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=coupons' \ -d 'method=createCoupon' \ -d 'code=PARCEIRA15' \ -d 'discountType=value' -d 'discountValue=15' \ -d 'scope=category' -d 'scopeIds=12,34' \ -d 'useLimit=200' -d 'useLimitPerPerson=1' \ --data-urlencode 'startDate=2026-11-01 00:00:00' \ --data-urlencode 'endDate=2026-12-31 23:59:59'

Criar um cupom só de frete grátis para clientes escolhidos pelo CPF (sem code, a API gera o código e devolve na resposta):

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=coupons' \ -d 'method=createCoupon' \ -d 'discountType=value' -d 'discountValue=0' -d 'freeShipping=1' \ -d 'includeDocuments=12345678909' \ -d 'useLimit=50' -d 'useLimitPerPerson=1' \ --data-urlencode 'startDate=2026-11-01 00:00:00' \ --data-urlencode 'endDate=2026-11-15 23:59:59'

Listar os cupons valendo agora:

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=coupons' \ -d 'method=listCoupons' \ -d 'status=active' -d 'page=1' -d 'pageSize=50'

Encerrar uma campanha agora, trazendo o fim da validade para hoje:

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=coupons' \ -d 'method=updateCoupon' \ -d 'couponId=10' \ --data-urlencode 'endDate=2026-10-16 18:00:00'

Depois de mexer nos cupons pela API

Peça para quem cuida da loja conferir no painel: em Menu → Extensões → Promoções, a aba Cupons mostra o cupom com código, valor, limites e validade, nos filtros de ativos, a iniciar e expirados. Depois, teste o código no carrinho da loja publicada. Se a loja ainda não reconhecer o cupom, use Atualizar no menu, como no passo a passo do painel.

O passo a passo da tela está em Cupom: criando, gerenciando e aplicando cupons em sua loja virtual, e a conferência rápida quando o código não entra está em Cupom não aplica no carrinho: FAQ de conferência rápida.

Erros comuns

Veja também

• API - Como habilitar

• API do Interago: o que é e para que serve

• Cupom: criando, gerenciando e aplicando cupons em sua loja virtual

• Como limitar cupom por cliente

• Como organizar cupons que não se conflitam

• Como criar cupom de parceiro

• Como medir se o cupom gerou pedido