Get Coupon Performance Analytics

Server URLloading...

GET

/api/v1/external/analytics/coupons/performance

Send

Authorization

Header

Query

Reports what the authenticated creator’s discount coupons actually cost over a window you choose: the total discount given away, how many orders used a coupon, and which codes drove it.

Use this to judge which promotions to keep running, or to set discount spend against earnings from Get Mango Revenue Analytics. It answers "how much discount did this creator give away?" — for "how many coupons do they have?", use Get Coupon Analytics Summary instead. This operation returns aggregates only; to see the individual redemptions behind a figure, call List Transactions by Creator with the code in couponCodes.

Choosing the window. startDate and endDate are both required and have no default — there is no implicit "last 7 days". Both bounds are inclusive and are matched against the date each order was created, so an order created at exactly endDate is counted. Be careful here: the sibling Get Mango Revenue Analytics operation uses an exclusive end bound, so the same pair of timestamps does not select the same set of orders in both. Both are absolute ISO 8601 instants, so convert your local day boundaries yourself. endDate must be on or after startDate and at most 90 days after it; for a longer report, call this operation once per 90-day slice. Equal timestamps are accepted and select orders created at that exact instant; a window entirely in the future returns 200 with zeros rather than an error.

What counts as a redemption. One redemption is one order that used one of the creator’s own coupons and was actually paid for. Refunded orders are included: a refund reverses the payment but not the fact that the coupon was redeemed, so this figure is deliberately higher than a refund-adjusted revenue report would suggest. Orders that were only started, or that failed, are excluded, as are orders that used a TagMango marketing coupon rather than the creator’s own, and orders carrying the internal zero-cost, empty, or machine-generated UUID codes.

Amounts. Every amount is the discount the customer received, expressed in the creator’s own currency and echoed back to you as currency, with no exchange-rate conversion at read time. Amounts are not rounded, so a long decimal tail is normal and should be formatted on your side. An order can count as a redemption while contributing 0, when it carries no discount amount in that currency; that is why totalRedemptions is reported alongside totalDiscountAvailed rather than left for you to infer.

Ranking and reconciliation. topPerformers holds at most limit codes — 3 by default, up to 10 — ordered by redemption count descending, then by discount descending, with no further tie-break. It is a shortlist, not a page: there is no cursor and no residual bucket, so when more than limit distinct codes were used, the listed discountAvailed values add up to less than totalDiscountAvailed and the remainder is simply not itemised. Raise limit to see more; to retrieve the full tail, list transactions instead. Codes that differ only in capitalisation are ranked as separate entries.

Freshness. Analytics are served from TagMango’s reporting store rather than the live transactional one, so a redemption taken moments ago may not be reflected yet, and no staleness bound is guaranteed. Two identical requests can therefore return slightly different figures as that store catches up.

Rejected requests. A missing, unparseable, out-of-order, or over-90-day date pair, or a limit outside 1–10, is rejected before any data is read, and every failing rule is reported at once. The body carries the failures as a list of messages such as "Start date is required" or "limit must not be greater than 10".

Query Parameters

Header Parameters

Response Body

curl -X GET "https://api-prod-new.tagmango.com/api/v1/external/analytics/coupons/performance?startDate=2026-08-01T00%3A00%3A00.000Z&endDate=2026-08-26T00%3A00%3A00.000Z" \  -H "x-whitelabel-host: string"

{
  "totalDiscountAvailed": 387100,
  "totalRedemptions": 514,
  "currency": "INR",
  "topPerformers": [
    {
      "code": "EARLYBIRD",
      "uses": 209,
      "discountAvailed": 62700
    }
  ]
}

{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "success": false,
  "message": "Invalid request",
  "result": "Invalid request"
}

{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "result": "Invalid token",
  "success": false
}

{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "WORKSHOP_MANGO_FORBIDDEN",
  "message": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "result": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "success": false
}

{
  "code": 429,
  "type": "Too Many Requests",
  "statusMessage": "TOO_MANY_REQUESTS",
  "message": "Request limit exceeded. try after 10 seconds",
  "result": "Request limit exceeded. try after 10 seconds",
  "success": false
}