List used coupons
One row per normalized coupon code used in the store's invoiced orders of the period. Codes are normalized per platform (trimmed and upper-cased; on Tray, the part before /), so BemVindo10 and BEMVINDO10 are one coupon. VTEX, Shopify and Tray carry coupons; other platforms answer an empty list. The discount is the whole order's discount, not only the coupon's share. 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 normalized coupon code.
length <= 120minOrders?numberInclusive lower bound on orders (orders that used the coupon). Must not exceed the matching max when both are sent. Applies to data, totals (except totalOrders and periodCouponOrders) and pagination.
0 <= valuemaxOrders?numberInclusive upper bound on orders (orders that used the coupon).
0 <= valueminUnits?numberInclusive lower bound on units (net units of those orders). Must not exceed the matching max when both are sent. Applies to data, totals (except totalOrders and periodCouponOrders) and pagination.
0 <= valuemaxUnits?numberInclusive upper bound on units (net units of those orders).
0 <= valueminNetRevenue?numberInclusive lower bound on netRevenue (net revenue of those orders). Must not exceed the matching max when both are sent. Applies to data, totals (except totalOrders and periodCouponOrders) and pagination.
0 <= valuemaxNetRevenue?numberInclusive upper bound on netRevenue (net revenue of those orders).
0 <= valueminDiscountValue?numberInclusive lower bound on discountValue (order discount of those orders). Must not exceed the matching max when both are sent. Applies to data, totals (except totalOrders and periodCouponOrders) and pagination.
0 <= valuemaxDiscountValue?numberInclusive upper bound on discountValue (order discount of those orders).
0 <= valuesortBy?stringSort field. Nulls sort last in both directions; ties are broken by couponCode ascending.
"orders""couponCode""orders""units""grossValue""discountValue""netRevenue""averageTicket""discountRate"sortOrder?string"desc""asc""desc"page?integer1 <= value <= 100001pageSize?integer1 <= value <= 10025Paginated coupon rows with totals
application/json- response
data*array<>totals*period*Period actually applied, after defaults.
asOf*|Freshness of the period's data: the older of the latest sales refresh and the latest coupon refresh. null when the period has no order.
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 }}