Reports & Analytics API

Generate aggregate performance statistics, commission time-series charts, top-earner leaderboards, campaign distribution, payout summaries, and detailed coupon redemption reports.

Authentication & Scopes

All endpoints require a Bearer access token with the reports:read scope. See Authentication.

Authorization: Bearer <access_token>

Endpoints Summary

Core Performance Reports

Coupon Performance Reports

Performance analytics and payout overview for affiliate programs. Retrieve stat cards with trend indicators, time-series commission charts, affiliate leaderboards, campaign breakdowns, payout history, and full CSV exports.

All endpoints require a Bearer access token with the appropriate scope. See Prerequisites & Authentication.

Endpoints

Common Query Parameters

All endpoints accept date range filters. When omitted, defaults to the last 30 days.

Report Stats — GET /v1/reports/stats

Returns four headline metrics with percentage trends compared to the previous period of equal length.

Example

curl "https://api.heldsway.com/api/v1/reports/stats?from=2026-03-17&to=2026-04-16" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Report statistics retrieved.",
  "data": {
    "total_commission_paid": 28.00,
    "pending_payouts": 14.00,
    "conversion_rate": 3.2,
    "total_referral_clicks": 2,
    "trends": {
      "commission_paid": 14.0,
      "pending_payouts": 0.0,
      "conversion_rate": 1.1,
      "referral_clicks": -8.3
    },
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16",
      "location_id": null,
      "source_domain": null
    }
  }
}

Response Fields

Trend Calculation

Trends compare the requested date range against the immediately preceding period of equal length. For example, if from=2026-03-17 and to=2026-04-16 (31 days), the previous period is 2026-02-14 to 2026-03-16.

• Commission and clicks: ((current - previous) / previous) * 100, rounded to 1 decimal place. Returns 0.0 when the previous period value is zero.
• Conversion rate: Absolute difference in percentage points (current_rate - previous_rate), rounded to 1 decimal place.

Commission Chart — GET /v1/reports/commission-chart

Returns time-series data for rendering a commission-over-time bar chart. Supports daily, weekly, or monthly granularity.

Query Parameters

Example

curl "https://api.heldsway.com/api/v1/reports/commission-chart?from=2026-04-01&to=2026-04-16&granularity=daily" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Commission chart data retrieved.",
  "data": {
    "granularity": "daily",
    "labels": ["Apr 01", "Apr 02", "Apr 03", "Apr 04", "Apr 05"],
    "data": [4.50, 0.00, 12.00, 0.00, 7.00],
    "filters": {
      "from": "2026-04-01",
      "to": "2026-04-16"
    }
  }
}

Response Fields

Label Format by Granularity

Empty time buckets are filled with 0.00 to ensure the chart has no gaps.

Top Affiliates — GET /v1/reports/top-affiliates

Returns the top-performing affiliates ranked by commission earned within the date range. Only affiliates with at least one conversion or click in the period are included.

Query Parameters

Example

curl "https://api.heldsway.com/api/v1/reports/top-affiliates?from=2026-03-17&to=2026-04-16&limit=5" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Top affiliates retrieved.",
  "data": {
    "items": [
      {
        "affiliate_id": 1,
        "name": "Salman",
        "referral_code": "SALMAN2026",
        "earned": 140.00,
        "clicks": 2,
        "conversions": 5
      }
    ],
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16",
      "location_id": null,
      "source_domain": null
    }
  }
}

Response Fields

Clicks by Campaign — GET /v1/reports/clicks-by-campaign

Returns referral click counts grouped by the campaign tag on referral links. All active campaigns for the business are included, even those with zero clicks in the date range.

Query Parameters

Example

curl "https://api.heldsway.com/api/v1/reports/clicks-by-campaign?from=2026-03-17&to=2026-04-16" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Clicks by campaign retrieved.",
  "data": {
    "items": [
      {
        "campaign": "mountain_rentals_brand",
        "clicks": 0
      },
      {
        "campaign": "women_skier_interest",
        "clicks": 0
      },
      {
        "campaign": "winter_sale",
        "clicks": 0
      },
      {
        "campaign": null,
        "clicks": 2
      }
    ],
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16",
      "location_id": null,
      "source_domain": null
    }
  }
}

Response Fields

Results are ordered by clicks descending. The null campaign entry (representing links without a campaign tag) is always listed last.

Payouts — GET /v1/reports/payouts

Returns a paginated list of payout records with optional filtering by status and affiliate.

Query Parameters

Example

curl "https://api.heldsway.com/api/v1/reports/payouts?status=completed&per_page=10" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Payouts retrieved.",
  "data": {
    "items": [
      {
        "id": 1,
        "affiliate_id": 1,
        "affiliate_name": "Salman",
        "amount": 28.00,
        "currency": "USD",
        "method": "bank_transfer",
        "status": "completed",
        "reference": "TXN-20260410-001",
        "paid_at": "2026-04-10T14:30:00.000000Z",
        "created_at": "2026-04-10T14:00:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 15,
      "total": 1,
      "last_page": 1
    },
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16"
    }
  }
}

Response Fields

Date Range Behavior

Date range filters are applied differently based on payout status:

• Completed payouts: filtered by paid_at (when the payment was made)
• Pending/failed payouts: filtered by created_at (when the payout was recorded)

This ensures completed payouts appear in the period they were paid, not when they were initially created.

Export Report — GET /v1/reports/export

Downloads a CSV file containing report data. By default exports all sections; use the sections parameter to select specific sections.

Query Parameters

Available Sections

Example

curl "https://api.heldsway.com/api/v1/reports/export?from=2026-04-01&to=2026-04-16&sections=stats,top_affiliates" \
  -H "Authorization: Bearer <access_token>" \
  -o affiliate-reports.csv

Success Response — HTTP 200

Content-Type: text/csv Content-Disposition: attachment; filename="affiliate-reports-2026-04-16.csv"

"--- Report Stats ---"
Metric,Value,Trend (%)
Total Commission Paid,28.00,14.0
Pending Payouts,14.00,0.0
Conversion Rate (%),3.2,1.1
Total Referral Clicks,2,-8.3

"--- Top Affiliates ---"
Name,Referral Code,Earned,Clicks,Conversions
Salman,SALMAN2026,140.00,2,5

"--- Clicks by Campaign ---"
Campaign,Clicks
mountain_rentals_brand,0
women_skier_interest,0
winter_sale,0
(no campaign),2

"--- Commission Over Time (daily) ---"
Date,Commission
Apr 01,4.50
Apr 02,0.00
Apr 03,12.00

"--- Payouts ---"
Affiliate,Amount,Currency,Method,Status,Reference,Paid At,Created At
Salman,28.00,USD,bank_transfer,completed,TXN-20260410-001,2026-04-10 14:30:00,2026-04-10 14:00:00

CSV Structure

• Each section is separated by a header row in the format --- Section Name ---
• Sections appear in the order: stats, top affiliates, clicks by campaign, commission chart, payouts
• When sections is specified, only the requested sections appear
• Unknown section keys in the sections parameter are silently ignored
• Payout timestamps use YYYY-MM-DD HH:MM:SS format (not ISO 8601)

Payout Status Workflow

  ┌─────────┐
  │ pending  │ ← initial state (payout recorded)
  └────┬─────┘
       │
  ┌────┴────┐
  ▼         ▼
┌───────────┐ ┌────────┐
│ completed │ │ failed │
└───────────┘ └────────┘

• **pending**: Payout has been recorded but not yet processed
• **completed**: Payment was successfully processed (paid_at is set)
• **failed**: Payment processing failed

Error Reference

Error Response Format

A validation failure returns Laravel’s standard validation body:

{
  "message": "The selected granularity is invalid.",
  "errors": {
    "granularity": ["The selected granularity is invalid."]
  }
}

Every other error uses the standard envelope (see Error Reference in the Affiliate Management API section).

Rate Limiting

Exceeding the limit returns HTTP 429 Too Many Requests with error code RATE_LIMIT_EXCEEDED.

Coupon Reports

Coupon (discount code) performance for the business: headline stats, a daily redemptions chart, top coupons by revenue, a paginated performance table, per-coupon conversion drill-down, coupon-linked referral links, and a CSV export. Source: Modules\AffiliateSupport\Http\Controllers\Api\CouponReportApiController, backed by ReportingService.

Every coupon report endpoint accepts the date range below; the other parameters are listed per endpoint.

A redemption is a conversion of this business that has a discount code, is not cancelled, and has converted_at inside the range ($0 orders count). Gross sales add each conversion’s subtotal, or its order_total when subtotal is 0 or empty.

Coupon Stats

Headline coupon metrics with trends against the previous period of equal length (source: CouponReportApiController::stats()).

GET /v1/reports/coupons/stats

Required scope: reports:read Rate limit: 120 requests/minute

Query Parameters

from, to only (rules from CouponReportStatsRequest::rules()).

Example Request

curl "https://api.heldsway.com/api/v1/reports/coupons/stats?from=2026-03-17&to=2026-04-16" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "Coupon report statistics retrieved.",
  "data": {
    "total_redemptions": 12,
    "gross_sales": 1840.5,
    "net_revenue": 1650.25,
    "total_discount": 190.25,
    "total_commission": 184.05,
    "avg_order_value": 153.38,
    "conversion_rate": 40,
    "trends": {
      "total_redemptions": 20,
      "gross_sales": 12.4,
      "net_revenue": 10.1,
      "total_discount": 35.2,
      "total_commission": 12.4,
      "avg_order_value": -6.3,
      "conversion_rate": 100
    },
    "filters": { "from": "2026-03-17", "to": "2026-04-16" }
  }
}

Response Fields

Error Responses

Coupon Redemptions Chart

Daily count of redemptions across the range (source: CouponReportApiController::redemptionsChart()).

GET /v1/reports/coupons/redemptions-chart

Required scope: reports:read Rate limit: 120 requests/minute

Query Parameters

from, to only (rules from CouponReportStatsRequest::rules()).

Example Request

curl "https://api.heldsway.com/api/v1/reports/coupons/redemptions-chart?from=2026-04-01&to=2026-04-03" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "Coupon redemptions chart data retrieved.",
  "data": {
    "labels": ["Apr 01", "Apr 02", "Apr 03"],
    "data": [2, 0, 5],
    "filters": { "from": "2026-04-01", "to": "2026-04-03" }
  }
}

labels has one M d entry for every day in the range; days without redemptions have 0 in data.

Error Responses

Top Coupons

Coupons ranked by revenue in the range (source: CouponReportApiController::top()).

GET /v1/reports/coupons/top

Required scope: reports:read Rate limit: 120 requests/minute

Query Parameters

Rules from CouponReportTopRequest::rules(), plus from / to.

Example Request

curl "https://api.heldsway.com/api/v1/reports/coupons/top?limit=3" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "Top coupons by revenue retrieved.",
  "data": {
    "labels": ["SUMMER20", "JANE15", "WELCOME10"],
    "data": [980.5, 540, 320.75],
    "filters": { "from": "2026-03-17", "to": "2026-04-16" }
  }
}

labels[i] is a coupon code and data[i] the revenue of its redemptions — per order, subtotal (or order_total when subtotal is 0 or empty) minus discount_applied, never below 0 per order — ordered by revenue descending.

Error Responses

Coupon Performance

Paginated table of the business’s discount codes (soft-deleted codes excluded) with their redemption totals in the range (source: CouponReportApiController::performance()). Only redemptions attributed to an affiliate are counted here; codes with no redemptions are listed with zeros.

GET /v1/reports/coupons/performance

Required scope: reports:read Rate limit: 120 requests/minute

Query Parameters

Rules from CouponReportPerformanceRequest::rules(), plus from / to.

Example Request

curl "https://api.heldsway.com/api/v1/reports/coupons/performance?status=active&sort_by=redemptions&per_page=10" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "Coupon performance table retrieved.",
  "data": {
    "items": [
      {
        "id": 57,
        "code": "JANE15",
        "affiliate_name": "Jane Smith",
        "affiliate_code": "JANE2026",
        "type": "percentage",
        "value": "15.00",
        "redemptions": 4,
        "gross_sales": 540,
        "discount_given": 81,
        "net_revenue": 459,
        "commission": 68.85,
        "aov": 135,
        "first_used": "2026-03-20 14:03:11",
        "last_used": "2026-04-12 09:41:02",
        "is_active": true,
        "expires_at": null
      }
    ],
    "meta": { "current_page": 1, "per_page": 10, "total": 1, "last_page": 1 },
    "filters": { "from": "2026-03-17", "to": "2026-04-16" }
  }
}

Response Fields

Error Responses

Coupon Conversions (Drill-down)

The latest 100 conversions that used one coupon (source: CouponReportApiController::drillDown()). Only conversions of this business that are attributed to an affiliate, not cancelled, and fall inside the range are returned, newest first ($0 orders included). An unknown coupon ID returns an empty list, not 404.

GET /v1/reports/coupons/{id}/conversions

Required scope: reports:read Rate limit: 120 requests/minute

Path Parameters

Query Parameters

from, to only (rules from CouponReportStatsRequest::rules()).

Example Request

curl "https://api.heldsway.com/api/v1/reports/coupons/57/conversions" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "Coupon drill-down data retrieved.",
  "data": {
    "conversions": [
      {
        "order_id": "ORD-10492",
        "subtotal": 150,
        "discount_applied": 22.5,
        "commission_amount": 19.13,
        "status": "approved",
        "converted_at": "2026-04-12T09:41:02.000000Z",
        "affiliate_code": "JANE2026"
      }
    ],
    "filters": { "from": "2026-03-17", "to": "2026-04-16" }
  }
}

subtotal falls back to order_total when the conversion has no subtotal. status is a conversion status value (see module-8 §9.3 enums).

Error Responses

Coupon-Linked Referral Links

Referral links that have a discount code attached, ranked by clicks in the range (source: CouponReportApiController::links() → ReportingService::couponLinksPerformance()).

GET /v1/reports/coupons/links

Required scope: reports:read Rate limit: 120 requests/minute

Query Parameters

Rules from CouponReportLinksRequest::rules(), plus from / to.

Example Request

curl "https://api.heldsway.com/api/v1/reports/coupons/links?discount_code_id=57" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "Coupon-linked referral links retrieved.",
  "data": {
    "items": [
      {
        "slug": "jane-promo",
        "destination_url": "https://example.com/promo",
        "campaign": "Spring 2026",
        "product_id": null,
        "product_name": null,
        "affiliate_code": "JANE2026",
        "discount_code": { "id": 57, "code": "JANE15", "type": "percentage", "value": "15.00" },
        "clicks": 40,
        "conversions": 4,
        "conversion_rate": 10,
        "revenue": 540,
        "commission": 68.85
      }
    ],
    "filters": { "from": "2026-03-17", "to": "2026-04-16" }
  }
}

Response Fields

A query failure is logged and returns 200 with an empty items array.

Error Responses

Export Coupon Report

Download the coupon performance table as CSV (source: CouponReportApiController::export()). It applies the same filters as Coupon Performance but ignores sort_by, sort_dir, per_page and page: rows are ordered by gross sales descending, capped at 10,000.

GET /v1/reports/coupons/export

Required scope: reports:read Rate limit: 30 requests/minute

Also requires the real-time-dashboard-csv-export plan feature.

Query Parameters

Same as Coupon Performance (CouponReportPerformanceRequest); only from, to, status, affiliate_ids[] and search affect the output.

Example Request

curl "https://api.heldsway.com/api/v1/reports/coupons/export?status=active" \
  -H "Authorization: Bearer <access_token>" \
  -o coupon-reports.csv

Success Response — 200 OK

Content-Type: text/csv Content-Disposition: attachment; filename="coupon-reports-2026-04-16.csv"

Code,Affiliate,Type,Value,Redemptions,"Gross Sales","Discount Given","Net Revenue",Commission,AOV,"First Used","Last Used",Status
JANE15,"Jane Smith",percentage,15.00,4,540,81,459,68.85,135,2026-03-20T14:03:11Z,2026-04-12T09:41:02Z,Active

First Used and Last Used are the first and last converted_at in the range, in UTC, as ISO 8601 with a Z suffix (empty when the code has no redemptions). Status is Active or Inactive from the code’s is_active flag only; an active code past its expiry still exports as Active.

Error Responses

The export has no error handler of its own: a failure while building the rows returns Laravel’s generic 500 JSON body.