List discounts by name
One row per discount that made the discount of the store's invoiced orders in the period: coupons, automatic and shipping promotions, manual and order-level discounts, grouped by kind and name. A discount is named by its normalized coupon code first, else by the name the platform gave it; an unnamed discount is kept apart by its technical reference (VTEX promotion id, Tray source field) and has name: null, while unnamed Shopify discounts collapse into one row per kind. The part of the orders' discount no named discount explains is never a row: it is reported in unattributed. discountValue is null when the platform does not separate the discount's money (a VTEX coupon, whose money sits inside a promotion). VTEX, Shopify and Tray carry discounts; other platforms answer an empty list. Responses are cached for 30 minutes.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringOrganization that owns the store.
uuidintegrationId*stringStore identifier: the sourceIntegrationId returned by GET /v1/products/integrations (a UUID or a <channel>:<identifier> store key).
dateFrom?stringFirst day of the period (inclusive), YYYY-MM-DD. Without dateFrom and dateTo the period is the current month, from its first day to today in the America/Sao_Paulo calendar. Only dateTo: from the first day of its month. Only dateFrom: until today. The rules apply to the resulting period, so a lone date is held to them too: neither date may be in the future, dateFrom must be on or before dateTo, and the period spans at most 365 days (a lone dateFrom at most 365 days before today). Otherwise 400.
datedateTo?stringLast day of the period (inclusive), YYYY-MM-DD. Cannot be in the future (today in the America/Sao_Paulo calendar is the latest accepted day), also when sent alone; the period spans at most 365 days. Otherwise 400.
datesearch?stringCase-insensitive substring match on the discount's name: the normalized coupon code, or the promotion name the platform gave. Unnamed discounts never match.
length <= 120minOrders?numberInclusive lower bound on orders (orders that carried the discount). Must not exceed the matching max when both are sent. Applies to data, totals.discounts, totals.discountValue and pagination; the period totals and unattributed ignore it.
0 <= valuemaxOrders?numberInclusive upper bound on orders (orders that carried the discount).
0 <= valueminDiscountValue?numberInclusive lower bound on discountValue. Items whose discountValue is null (value not separable, e.g. a VTEX coupon) are always left out when this bound is sent, even minDiscountValue=0; they are not treated as 0. Must not exceed the matching max when both are sent. Applies to data, totals.discounts, totals.discountValue and pagination; the period totals and unattributed ignore it.
0 <= valuemaxDiscountValue?numberInclusive upper bound on discountValue. Items whose discountValue is null (value not separable, e.g. a VTEX coupon) are always left out when this bound is sent, even minDiscountValue=0; they are not treated as 0.
0 <= valuesortBy?stringSort field. Nulls sort last in both directions; ties are broken by name ascending (unnamed last), then kind and reference.
"orders""name""kind""orders""discountValue""shareOfDiscount""averageDiscountPerOrder"sortOrder?string"desc""asc""desc"page?integer1 <= value <= 100001pageSize?integer1 <= value <= 10025Paginated discount rows with totals and the unattributed residual
application/json- response
data*array<>totals*unattributed*The part of the orders' discount no named discount explains (the residual), over the whole period. Never listed in data.
period*Period actually applied, after defaults.
asOf*|Freshness of the period's discount rows: their latest refresh. null when the period has no discounted order.
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 }}