Cupons: consulta

Lista os cupons da loja com filtros e lê um cupom pelo id numérico.

Um cupom (voucher) é um código que o cliente digita no checkout para ganhar desconto ou frete grátis. Use estas duas operações para sincronizar os cupons com um sistema de marketing, conferir quantas vezes um código foi usado ou montar um relatório.

O cupom pode ser da loja inteira (vendor_id nulo) ou de um seller (vendor_id com o UUID do lojista); nesse caso o desconto vale só para os itens daquele seller. Para criar e alterar, veja Cupons: escrita.

GET/api/v2/couponsAdmin

Listar cupons

A lista vem da criação mais recente para a mais antiga. Não há parâmetro de ordenação.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 vira 100.

searchstring

Texto que o código ou a descrição contém, sem diferenciar maiúsculas.

statusstring

activeexpiredinactiveexhausted

active: ligado e dentro da validade. expired: a data de fim já passou. inactive: desligado (is_active falso). exhausted: já usado o máximo de vezes (max_uses maior que zero e used_count igual ou maior). Outro valor é ignorado e a lista sai sem filtro.

typestring

fixedpercentagefree_shipping

Tipo do desconto. Valor desconhecido é ignorado.

vendor_iduuid

Somente cupons deste seller.

marketplace_onlyboolean

true1yes

Somente cupons da loja inteira (sem seller). Se vendor_id também vier, o vendor_id vale.

fieldsstring

Chaves a devolver em cada item, separadas por vírgula (id,code,is_active).

GET/api/v2/coupons/{id}Admin

Ler um cupom

Devolve um cupom. O id é o inteiro do campo id da lista, não o código.

Parâmetros de caminho

idintegerobrigatório

Id numérico do cupom. Texto, zero ou negativo é recusado com 400.

Parâmetros de consulta

fieldsstring

Chaves a devolver, separadas por vírgula.

Exemplo de requisição

bash

curl "$BASE_URL/api/v2/coupons?status=active&type=percentage&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cupons retornados

json

{
  "data": [
    {
      "id": 79,
      "vendor_id": null,
      "code": "INVERNO10",
      "type": "percentage",
      "value": 1000,
      "min_order": 5000,
      "max_uses": 100,
      "used_count": 12,
      "max_per_user": 1,
      "starts_at": null,
      "expires_at": "2026-12-31T23:59:59Z",
      "is_active": true,
      "description": "Campanha de inverno",
      "created_at": "2026-09-15T14:20:55.610138Z",
      "updated_at": "2026-09-15T14:20:55.610138Z"
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 20, "total": 38, "total_pages": 2 } }
}

Campos da resposta

data[].idinteger

Id numérico do cupom.

data[].vendor_iduuid | null

Seller dono do cupom. null vale para a loja inteira.

data[].codestring

Código que o cliente digita. Sempre em maiúsculas.

data[].typestring

fixedpercentagefree_shipping

fixed: valor fixo em centavos. percentage: porcentagem em pontos-base. free_shipping: frete grátis (o value é ignorado).

data[].valueinteger

Em fixed, centavos (500 = R$ 5,00). Em percentage, pontos-base (1000 = 10%, 10000 = 100%).

data[].min_orderinteger

Pedido mínimo em centavos. 0 é sem mínimo.

data[].max_usesinteger

Limite de usos no total. 0 é ilimitado.

data[].used_countinteger

Quantas vezes o cupom já foi usado.

data[].max_per_userinteger

Limite de usos por cliente. 0 é ilimitado.

data[].starts_atstring | null

Início da validade (RFC 3339). null vale desde já.

data[].expires_atstring | null

Fim da validade (RFC 3339). null nunca expira.

data[].is_activeboolean

Falso desliga o cupom sem apagá-lo.

data[].descriptionstring

Nota interna. Pode ser vazia.

data[].created_atstring

Criação (RFC 3339, UTC).

data[].updated_atstring

Última alteração (RFC 3339, UTC).

meta.paginationobject

page, per_page, total (todos os cupons que atendem ao filtro) e total_pages.

A leitura de um cupom (GET /api/v2/coupons/{id}) devolve { "data": { ... } } com os mesmos campos, sem meta.

Erros

Status	Quando	Corpo
400	`{id}` não numérico	`{"error":{"code":"bad_request","message":"coupon id must be a positive integer"}}`
400	`{id}` igual a `0` ou negativo	`{"error":"invalid id parameter"}`
401	Sem token	`{"error":"missing authorization header"}`
403	Token de seller ou de cliente	`{"error":"insufficient permissions"}`
404	Cupom inexistente	`{"error":{"code":"not_found","message":"coupon not found"}}`

Veja também

Cupons: consulta

Lista os cupons da loja com filtros e lê um cupom pelo id numérico.

GET/api/v2/couponsAdmin

Listar cupons

A lista vem da criação mais recente para a mais antiga. Não há parâmetro de ordenação.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 vira 100.

searchstring

Texto que o código ou a descrição contém, sem diferenciar maiúsculas.

statusstring

activeexpiredinactiveexhausted

typestring

fixedpercentagefree_shipping

Tipo do desconto. Valor desconhecido é ignorado.

vendor_iduuid

Somente cupons deste seller.

marketplace_onlyboolean

true1yes

Somente cupons da loja inteira (sem seller). Se vendor_id também vier, o vendor_id vale.

fieldsstring

Chaves a devolver em cada item, separadas por vírgula (id,code,is_active).

GET/api/v2/coupons/{id}Admin

Ler um cupom

Devolve um cupom. O id é o inteiro do campo id da lista, não o código.

Parâmetros de caminho

idintegerobrigatório

Id numérico do cupom. Texto, zero ou negativo é recusado com 400.

Parâmetros de consulta

fieldsstring

Chaves a devolver, separadas por vírgula.

Exemplo de requisição

bash

curl "$BASE_URL/api/v2/coupons?status=active&type=percentage&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cupons retornados

json

{
  "data": [
    {
      "id": 79,
      "vendor_id": null,
      "code": "INVERNO10",
      "type": "percentage",
      "value": 1000,
      "min_order": 5000,
      "max_uses": 100,
      "used_count": 12,
      "max_per_user": 1,
      "starts_at": null,
      "expires_at": "2026-12-31T23:59:59Z",
      "is_active": true,
      "description": "Campanha de inverno",
      "created_at": "2026-09-15T14:20:55.610138Z",
      "updated_at": "2026-09-15T14:20:55.610138Z"
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 20, "total": 38, "total_pages": 2 } }
}

Campos da resposta

data[].idinteger

Id numérico do cupom.

data[].vendor_iduuid | null

Seller dono do cupom. null vale para a loja inteira.

data[].codestring

Código que o cliente digita. Sempre em maiúsculas.

data[].typestring

fixedpercentagefree_shipping

fixed: valor fixo em centavos. percentage: porcentagem em pontos-base. free_shipping: frete grátis (o value é ignorado).

data[].valueinteger

Em fixed, centavos (500 = R$ 5,00). Em percentage, pontos-base (1000 = 10%, 10000 = 100%).

data[].min_orderinteger

Pedido mínimo em centavos. 0 é sem mínimo.

data[].max_usesinteger

Limite de usos no total. 0 é ilimitado.

data[].used_countinteger

Quantas vezes o cupom já foi usado.

data[].max_per_userinteger

Limite de usos por cliente. 0 é ilimitado.

data[].starts_atstring | null

Início da validade (RFC 3339). null vale desde já.

data[].expires_atstring | null

Fim da validade (RFC 3339). null nunca expira.

data[].is_activeboolean

Falso desliga o cupom sem apagá-lo.

data[].descriptionstring

Nota interna. Pode ser vazia.

data[].created_atstring

Criação (RFC 3339, UTC).

data[].updated_atstring

Última alteração (RFC 3339, UTC).

meta.paginationobject

page, per_page, total (todos os cupons que atendem ao filtro) e total_pages.

A leitura de um cupom (GET /api/v2/coupons/{id}) devolve { "data": { ... } } com os mesmos campos, sem meta.

Erros

Status	Quando	Corpo
400	`{id}` não numérico	`{"error":{"code":"bad_request","message":"coupon id must be a positive integer"}}`
400	`{id}` igual a `0` ou negativo	`{"error":"invalid id parameter"}`
401	Sem token	`{"error":"missing authorization header"}`
403	Token de seller ou de cliente	`{"error":"insufficient permissions"}`
404	Cupom inexistente	`{"error":{"code":"not_found","message":"coupon not found"}}`