Coupons

Which coupons your customers used, how many orders and units they moved, and how much discount they cost

What this analysis answers

The Coupons API lists every coupon code used in the store's invoiced orders over the period you choose, with the orders, units, gross value, discount and net revenue behind each one. The numbers follow the same rules as the V4MOS.AI platform, so you can load them straight into your BI tool.

Questions you can answer:

Which coupons bring in the most orders and revenue?
How much discount did each coupon cost, as a value and as a share of the gross value?
What share of the store's orders used a coupon at all?
What is the average ticket of orders that used a given coupon?

Getting started

Base URL: https://data.v4mos.ai. Every call requires your API credentials and the organizationId — see Authentication.

Call GET /v1/products/integrations?organizationId=… and take the store's sourceIntegrationId.
Call GET /v1/coupons with that value as integrationId.

Metrics

Field	What it is
`couponCode`	The coupon code, normalized: trimmed and upper-cased, so `BemVindo10` and `BEMVINDO10` are one coupon. On Tray, the part before `/` (Tray stores `CODE/value`).
`orders`	Invoiced orders in the period that used the coupon.
`units`	Net units of the items of those orders.
`grossValue`	The orders' gross value, before discount.
`discountValue`	The orders' discount.
`netRevenue`	Net sales of the items of those orders.
`averageTicket`	`netRevenue ÷ orders`. `null` when there is no order.
`discountRate`	`discountValue ÷ grossValue`, as a ratio (0.1 = 10%). `null` when the gross value is 0.
`shareOfCouponOrders`	`orders ÷ totals.couponOrders`: the coupon's share of all coupon orders.
`totals.totalOrders`	Every invoiced order of the period, with or without a coupon, including orders the coupon data does not cover yet.
`totals.periodCouponOrders`	Invoiced orders of the period that used any coupon. Use `totals.periodCouponOrders ÷ totals.totalOrders` for the share of orders with a coupon; it holds under any filter.

The discount is the whole order's

Platforms report one discount per order and do not say which promotion caused it. An order with a coupon and an automatic promotion reports both discounts together, under the coupon.

Filters and sorting

search matches part of the coupon code, ignoring case.
minOrders/maxOrders, minUnits/maxUnits, minNetRevenue/maxNetRevenue and minDiscountValue/maxDiscountValue are inclusive ranges. They filter data, pagination and totals, except totals.totalOrders and totals.periodCouponOrders.
sortBy accepts couponCode, orders, units, grossValue, discountValue, netRevenue, averageTicket and discountRate (default orders, descending). Ties are broken by coupon code.
page and pageSize (default 25, at most 100) page the list.

Common parameters

Parameter	Required	Description
`organizationId`	Yes	Organization UUID.
`integrationId`	Yes	The `sourceIntegrationId` returned by `GET /v1/products/integrations`.
`dateFrom` / `dateTo`	No	Period as `YYYY-MM-DD`. Default: the current month, from its first day to today. At most 365 days, no future dates; a lone date is held to the same rules once the missing bound is filled (a lone `dateTo` starts on the first of its month, a lone `dateFrom` ends today).

Platforms

VTEX, Shopify and Tray stores carry coupons. Other platforms answer an empty list.

Available endpoints

getList used coupons/v1/couponsOne row per normalized coupon code used in the store's invoiced orders of the period.

Coupons

What this analysis answersCopy Anchor Link

Getting startedCopy Anchor Link

MetricsCopy Anchor Link

Filters and sortingCopy Anchor Link

Common parametersCopy Anchor Link