Coupon analytics metrics and definitions

Affiliate Command loads the Coupon analytics modal from three IAS v2 endpoints:

The UI does not recompute these numbers — it renders the API payload. Changing the modal date range refetches /analytics and /analytics/products only; /analytics/redeemers is loaded once per coupon (lifetime).

Authentication and access

• Auth: Affiliate JWT (affiliateToken).
• Roles: AFFILIATE_SUPER_ADMIN and AFFILIATE_ADMIN only on all four coupon report routes (the three per-coupon analytics routes and GET .../used-on-orders). AFFILIATE_AGENT is not allowed. Agents are not in the affiliate permission matrix, so they are not gated by requireModuleAccess either — the route role list is what blocks them.
• Module: couponAnalytics with view on the three per-coupon analytics routes; full on GET .../used-on-orders.
• 404: Coupon id not found, or coupon belongs to another affiliate.
• 401 / 403: Missing/invalid token or insufficient role/module access.
• 422 (INVALID_FIELD): Invalid dateRange preset; dateRange=custom without startDate/endDate; bad YYYY-MM-DD; startDate after endDate.

Date range (KPIs and products only)

Query parameter dateRange defaults to last_7_days when omitted.

Affiliate Command typically opens the modal with last_thirty_days and sends an explicit dateRange on fetch.

Range application: KPIs and products filter on redeem redeemedAt (appliedAt, else redeem createdAt). They do not filter on order.createdAt.

Resolved bounds are echoed on data.range (startDate, endDate, preset) for KPI and products responses.

Redeem rows (before order qualify)

All three endpoints start from affiliate-scoped coupon redeems that are:

• status: APPLIED
• deleted: false
• Linked to a non-empty ecommerceOrder and patient (KPIs / products / redeemers pipelines)

Only redeems whose linked order qualifies (below) contribute to KPIs, products, redeemer segments, and retention.

Qualifying orders

A redemption counts toward analytics only when the linked ecommerce order qualifies. The same rules are implemented in buildCouponAnalyticsOrderQualifyExpr, buildCouponAnalyticsOrderQualifyStages, and buildCouponAnalyticsOrderLookupQualifyStages (KPIs, products, redeemers, retention, and coupons-used-on-orders).

Orders in processing, paid, or completed with partial refunds before status moves to refunded still qualify on the paid branch; after qualify, revenue uses net totals (see below).

Revenue and refunds: After qualification, order totalAmount on the pipeline is max(totalAmount - totalRefunded, 0). KPI revenueCollected and product line allocation use that net order total.

Within the selected date range, one qualifying redemption per order (earliest redeemedAt per order) feeds KPI uses, revenue, and discount totals.

Compared with GET /v2/ecommerceReports/coupons/used-on-orders

Both join APPLIED redeems to orders with the same core qualify pipeline. Contract differences:

KPI endpoint (GET .../analytics)

data.kpis

Two different “new vs returning” ideas (do not conflate):

• New to the affiliate — drives spendingPerNewUser and the users.new vs users.existingFirstUse split. Implemented as any earlier affiliate ecommerce order for the patient (any order status), not “first qualifying order only.” Non-qualifying or unpaid checkouts still count as prior orders for this rule.
• Returning on this coupon — users.returning only: patient has more than one qualifying deduped order on this coupon (lifetime). Independent of the affiliate new/existing split.

data.usageLimit

Lifetime only (not limited to the selected date range).

The analytics response does not include users, retention, or qualifiedUsed.

Redeemers endpoint (GET .../analytics/redeemers)

data.users (lifetime)

Each patient with at least one qualifying redeem on this coupon appears once. Segment assignment is per patient (lifetime qualifying orders, deduped by order):

Each bucket includes:

• count — distinct patients in the segment.
• pct — count ÷ totalDistinctRedeemers × 100.
• redemptions — qualifying deduped orders (lifetime) for patients in that segment.
• redemptionPct — redemptions ÷ totalRedemptions × 100 (use for relative performance bars on the Redeemers tab).

Also: totalDistinctRedeemers, totalRedemptions.

data.retention (new customers only)

Retention cohort = patients in the new segment at their first qualifying coupon redemption (lifetime). Returning and existing first use patients are excluded so blended retention is not inflated.

For each milestone day30, day60, day90, day180:

Label retention in the UI as new customer retention.

Products endpoint (GET .../analytics/products)

Same qualify rules and redeemedAt date filter as KPIs. Default limit 5 (max 50). Paginate to list all products in range.

Sort (server): revenue descending, then orders descending.

Affiliate Command UI (integration notes)

Response envelope

{
  "success": true,
  "data": { }
}

OpenAPI: CouponAnalyticsSuccessEnvelope, CouponAnalyticsRedeemersSuccessEnvelope, CouponAnalyticsProductsSuccessEnvelope.

Implementation reference in telegra-rest: src/ias/v2/ui/ecommerceReports/coupons/ (routes) and src/services/ecommerce/ecommerceReport/internal.js (qualify pipelines and aggregations).