Listar descontos por nome
Uma linha por desconto que compôs o desconto dos pedidos faturados da loja no período: cupons, promoções automáticas e de frete, descontos manuais e de pedido, agrupados por kind e nome. O desconto é nomeado primeiro pelo código de cupom normalizado e, na falta dele, pelo nome que a plataforma deu; um desconto sem nome fica separado pela reference técnica (id da promoção VTEX, campo de origem na Tray) e vem com name: null, enquanto os descontos sem nome do Shopify se juntam numa linha por kind. A parte do desconto dos pedidos que nenhum desconto nomeado explica nunca vira linha: ela vem em unattributed. discountValue é null quando a plataforma não separa o dinheiro do desconto (um cupom VTEX, cujo dinheiro está dentro de uma promoção). VTEX, Shopify e Tray têm descontos; as demais plataformas respondem uma lista vazia. 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 parcial, sem diferenciar maiúsculas e minúsculas, no nome do desconto: o código de cupom normalizado ou o nome da promoção que a plataforma deu. Descontos sem nome nunca entram na busca.
length <= 120minOrders?numberLimite inferior inclusivo de orders (pedidos que tiveram o desconto). Não pode passar do max correspondente quando os dois são enviados. Vale para data, totals.discounts, totals.discountValue e pagination; os totais do período e unattributed o ignoram.
0 <= valuemaxOrders?numberLimite superior inclusivo de orders (pedidos que tiveram o desconto).
0 <= valueminDiscountValue?numberLimite inferior inclusivo de discountValue. Itens com discountValue null (valor não separável, por exemplo um cupom VTEX) sempre ficam de fora quando este limite é enviado, mesmo com minDiscountValue=0; eles não contam como 0. Não pode passar do max correspondente quando os dois são enviados. Vale para data, totals.discounts, totals.discountValue e pagination; os totais do período e unattributed o ignoram.
0 <= valuemaxDiscountValue?numberLimite superior inclusivo de discountValue. Itens com discountValue null (valor não separável, por exemplo um cupom VTEX) sempre ficam de fora quando este limite é enviado, mesmo com minDiscountValue=0; eles não contam como 0.
0 <= valuesortBy?stringCampo de ordenação. Nulos vão para o fim nas duas direções; o desempate é por name crescente (sem nome por último), depois kind e reference.
"orders""name""kind""orders""discountValue""shareOfDiscount""averageDiscountPerOrder"sortOrder?string"desc""asc""desc"page?integer1 <= value <= 100001pageSize?integer1 <= value <= 10025Linhas de desconto paginadas, com totais e o resíduo não atribuído
application/json- response
data*array<>totals*unattributed*A parte do desconto dos pedidos que nenhum desconto nomeado explica (o resíduo), no período inteiro. Nunca aparece em data.
period*Período efetivamente aplicado, depois dos padrões.
asOf*|Frescor das linhas de desconto do período: a atualização mais recente delas. null quando o período não tem pedido com desconto.
date-timepagination*curl -X GET "https://example.com/v1/coupons/discounts?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=string"{ "data": [ { "name": "Black Friday", "code": null, "reference": null, "kind": "promotion", "platform": "VTEX", "orders": 120, "attributableOrders": 118, "discountValue": 5400, "valueAttribution": "mixed", "shareOfDiscount": 0.45, "averageDiscountPerOrder": 45.76 }, { "name": "BEMVINDO10", "code": "BEMVINDO10", "reference": null, "kind": "coupon", "platform": "VTEX", "orders": 80, "attributableOrders": 0, "discountValue": null, "valueAttribution": "not_attributed", "shareOfDiscount": null, "averageDiscountPerOrder": null }, { "name": null, "code": null, "reference": "8f1c2d3e-promo", "kind": "promotion", "platform": "VTEX", "orders": 12, "attributableOrders": 12, "discountValue": 240, "valueAttribution": "item_tags", "shareOfDiscount": 0.02, "averageDiscountPerOrder": 20 } ], "totals": { "discounts": 3, "discountValue": 5640, "ordersWithDiscount": 410, "totalDiscount": 12000, "attributedDiscount": 9600 }, "unattributed": { "orders": 95, "discountValue": 2400, "shareOfDiscount": 0.2 }, "period": { "from": "2026-10-01", "to": "2026-10-28" }, "asOf": "2026-10-28T06:00:00.000Z", "pagination": { "page": 1, "pageSize": 25, "total": 3, "totalPages": 1 }}