Listar cupons utilizados
Uma linha por código de cupom normalizado usado nos pedidos faturados da loja no período. Os códigos são normalizados por plataforma (sem espaços nas pontas e em maiúsculas; na Tray, a parte antes da /), então BemVindo10 e BEMVINDO10 são um cupom só. VTEX, Shopify e Tray têm cupons; as demais plataformas respondem uma lista vazia. O desconto é o do pedido inteiro, não só a parte do cupom. As respostas ficam em cache por 30 minutos.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringOrganização dona da loja.
uuidintegrationId*stringIdentificador da loja: o sourceIntegrationId retornado por GET /v1/products/integrations (um UUID ou uma chave de loja <canal>:<identificador>).
dateFrom?stringPrimeiro dia do período (inclusivo), YYYY-MM-DD. Sem dateFrom e dateTo, o período é o mês corrente, do dia 1º até hoje no calendário de America/Sao_Paulo. Só dateTo: a partir do dia 1º do mês dela. Só dateFrom: até hoje. As regras valem para o período resultante, então uma data sozinha também passa por elas: nenhuma data pode estar no futuro, dateFrom não pode passar de dateTo e o período tem no máximo 365 dias (um dateFrom sozinho, no máximo 365 dias antes de hoje). Fora disso, 400.
datedateTo?stringÚltimo dia do período (inclusivo), YYYY-MM-DD. Não pode estar no futuro (hoje no calendário de America/Sao_Paulo é o último dia aceito), inclusive quando enviado sozinho; o período tem no máximo 365 dias. Fora disso, 400.
datesearch?stringBusca parte do código de cupom normalizado, sem diferenciar maiúsculas e minúsculas.
length <= 120minOrders?numberLimite inferior inclusivo de orders (pedidos que usaram o cupom). Não pode passar do max correspondente quando os dois são enviados. Vale para data, totals (exceto totalOrders e periodCouponOrders) e pagination.
0 <= valuemaxOrders?numberLimite superior inclusivo de orders (pedidos que usaram o cupom).
0 <= valueminUnits?numberLimite inferior inclusivo de units (unidades líquidas desses pedidos). Não pode passar do max correspondente quando os dois são enviados. Vale para data, totals (exceto totalOrders e periodCouponOrders) e pagination.
0 <= valuemaxUnits?numberLimite superior inclusivo de units (unidades líquidas desses pedidos).
0 <= valueminNetRevenue?numberLimite inferior inclusivo de netRevenue (receita líquida desses pedidos). Não pode passar do max correspondente quando os dois são enviados. Vale para data, totals (exceto totalOrders e periodCouponOrders) e pagination.
0 <= valuemaxNetRevenue?numberLimite superior inclusivo de netRevenue (receita líquida desses pedidos).
0 <= valueminDiscountValue?numberLimite inferior inclusivo de discountValue (desconto desses pedidos). Não pode passar do max correspondente quando os dois são enviados. Vale para data, totals (exceto totalOrders e periodCouponOrders) e pagination.
0 <= valuemaxDiscountValue?numberLimite superior inclusivo de discountValue (desconto desses pedidos).
0 <= valuesortBy?stringCampo de ordenação. Nulos vão para o fim nas duas direções; empates são desfeitos por couponCode crescente.
"orders""couponCode""orders""units""grossValue""discountValue""netRevenue""averageTicket""discountRate"sortOrder?string"desc""asc""desc"page?integer1 <= value <= 100001pageSize?integer1 <= value <= 10025Linhas de cupom paginadas, com totais
application/json- response
data*array<>totals*period*Período efetivamente aplicado, depois dos padrões.
asOf*|Frescor dos dados do período: a mais antiga entre a última atualização das vendas e a última atualização dos cupons. null quando o período não tem pedido.
date-timepagination*curl -X GET "https://example.com/v1/coupons?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=string"{ "data": [ { "couponCode": "BEMVINDO10", "orders": 120, "units": 310, "grossValue": 25000.5, "discountValue": 2500, "netRevenue": 22500.5, "averageTicket": 187.5, "discountRate": 0.1, "shareOfCouponOrders": 0.25 } ], "totals": { "coupons": 14, "couponOrders": 480, "totalOrders": 3200, "periodCouponOrders": 512, "units": 1200, "grossValue": 98000, "discountValue": 9100, "netRevenue": 88900 }, "period": { "from": "2026-10-01", "to": "2026-10-28" }, "asOf": "2026-10-28T06:00:00.000Z", "pagination": { "page": 1, "pageSize": 25, "total": 14, "totalPages": 1 }}