Cupons

Quais cupons seus clientes usaram, quantos pedidos e unidades eles movimentaram e quanto desconto custaram

O que esta análise responde

A API de Cupons lista cada código de cupom usado nos pedidos faturados da loja no período que você escolher, com os pedidos, unidades, valor bruto, desconto e receita líquida de cada um. Os números seguem os mesmos critérios da plataforma V4MOS.AI, então você pode levá-los direto para o seu BI.

Perguntas que você consegue responder:

Quais cupons trazem mais pedidos e mais receita?
Quanto desconto cada cupom custou, em valor e em proporção do valor bruto?
Que parcela dos pedidos da loja usou algum cupom?
Qual o ticket médio dos pedidos que usaram um cupom?

Primeiros passos

URL base: https://data.v4mos.ai. Toda chamada exige suas credenciais de API e o organizationId — veja Autenticação.

Chame GET /v1/products/integrations?organizationId=… e pegue o sourceIntegrationId da loja.
Chame GET /v1/coupons com esse valor em integrationId.

Métricas

Campo	O que é
`couponCode`	O código do cupom, normalizado: sem espaços nas pontas e em maiúsculas, então `BemVindo10` e `BEMVINDO10` são um cupom só. Na Tray, a parte antes da `/` (a Tray grava `CODIGO/valor`).
`orders`	Pedidos faturados no período que usaram o cupom.
`units`	Unidades líquidas dos itens desses pedidos.
`grossValue`	Valor bruto desses pedidos, antes do desconto.
`discountValue`	Desconto desses pedidos.
`netRevenue`	Venda líquida dos itens desses pedidos.
`averageTicket`	`netRevenue ÷ orders`. `null` quando não há pedido.
`discountRate`	`discountValue ÷ grossValue`, em fração (0,1 = 10%). `null` quando o valor bruto é 0.
`shareOfCouponOrders`	`orders ÷ totals.couponOrders`: a parcela do cupom entre todos os pedidos com cupom.
`totals.totalOrders`	Todos os pedidos faturados do período, com ou sem cupom, inclusive os que os dados de cupom ainda não cobrem.
`totals.periodCouponOrders`	Pedidos faturados do período que usaram algum cupom. Use `totals.periodCouponOrders ÷ totals.totalOrders` para a parcela de pedidos com cupom; vale com qualquer filtro.

O desconto é do pedido inteiro

As plataformas informam um desconto por pedido e não dizem qual promoção o causou. Um pedido com cupom e promoção automática traz os dois descontos juntos, no cupom.

Filtros e ordenação

search busca parte do código do cupom, sem diferenciar maiúsculas e minúsculas.
minOrders/maxOrders, minUnits/maxUnits, minNetRevenue/maxNetRevenue e minDiscountValue/maxDiscountValue são faixas inclusivas. Elas filtram data, pagination e totals, exceto totals.totalOrders e totals.periodCouponOrders.
sortBy aceita couponCode, orders, units, grossValue, discountValue, netRevenue, averageTicket e discountRate (padrão orders, decrescente). Empates são desfeitos pelo código do cupom.
page e pageSize (padrão 25, máximo 100) paginam a lista.

Parâmetros comuns

Parâmetro	Obrigatório	Descrição
`organizationId`	Sim	UUID da organização.
`integrationId`	Sim	O `sourceIntegrationId` retornado por `GET /v1/products/integrations`.
`dateFrom` / `dateTo`	Não	Período em `YYYY-MM-DD`. Padrão: o mês corrente, do dia 1º até hoje. No máximo 365 dias, sem datas futuras; uma data sozinha passa pelas mesmas regras depois de completado o limite que falta (um `dateTo` sozinho começa no dia 1º do mês dele, um `dateFrom` sozinho termina hoje).

Plataformas

Lojas VTEX, Shopify e Tray têm cupons. As demais plataformas respondem uma lista vazia.

Endpoints disponíveis

getListar cupons utilizados/v1/couponsUma linha por código de cupom normalizado usado nos pedidos faturados da loja no período.

Cupons

O que esta análise respondeCopiar link da seção

Primeiros passosCopiar link da seção

MétricasCopiar link da seção

Filtros e ordenaçãoCopiar link da seção

Parâmetros comunsCopiar link da seção