Affiliate Analytics

GET /v1/affiliate/analytics

Fetch affiliate analytics data for a business. Supports multiple data sections (stats, trends, charts, tables, and paginated activity feeds), each with optional metric filtering and date range scoping.

Authentication

Requires a Bearer access token with the reports:read scope.

Authorization: Bearer <access_token>

Request

GET /v1/affiliate/analytics
Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Required	Default	Constraints	Description
section	string	Yes	—	See Sections below	The data section to retrieve
from	date	No	30 days ago	Must be ≤ to	Start of date range (YYYY-MM-DD)
to	date	No	Today	Must be ≤ today	End of date range (YYYY-MM-DD)
metrics	string	No	All metrics	Comma-separated	Filter which metrics to return
page	integer	No	1	≥ 1	Page number (paginated sections only)
per_page	integer	No	15	1–100	Results per page (paginated sections only)
top_limit	integer	No	10	1–50	Max rows returned (tables section only)

Sections

The section parameter controls what data is returned. Each section returns a different data shape.

stats — Aggregate Totals

Returns scalar numeric values for each metric over the date range.

Available metrics (pass as metrics=total_clicks,total_revenue etc.):

Metric	Type	Description
total_clicks	integer	Total affiliate link clicks
total_pageviews	integer	Total page views tracked
unique_visitors	integer	Unique visitor sessions
pages_per_visit	float	Average pages viewed per session
total_conversions	integer	Total completed conversions/orders
total_revenue	float	Total order revenue (sum of order totals)
total_commission	float	Total commission earned by affiliates
conversion_rate	float	Conversions ÷ clicks (percentage)
total_product_views	integer	Total product view events
total_add_to_carts	integer	Total add-to-cart events
total_remove_from_carts	integer	Total remove-from-cart events
total_thank_you_views	integer	Total thank-you page views
cart_to_conversion_rate	float	Conversions ÷ add-to-carts (percentage)

Example request & response:

curl "https://heldsway.com/api/v1/affiliate/analytics?section=stats&from=2024-01-01&to=2024-01-31&metrics=total_clicks,total_conversions,total_revenue" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "message": "OK",
  "data": {
    "filters": { "from": "2024-01-01", "to": "2024-01-31" },
    "section": "stats",
    "stats": {
      "total_clicks": 1842,
      "total_conversions": 73,
      "total_revenue": 12450.00
    }
  }
}

trends — Period-over-Period Change

Returns a percentage change value for each metric comparing the requested period to the preceding equal-length period.

Available metrics:

Metric	Description
clicks	Click volume trend
pageviews	Pageview trend
visitors	Unique visitor trend
conversions	Conversion count trend
revenue	Revenue trend
commission	Commission trend
product_views	Product view trend
add_to_carts	Add-to-cart trend

Example response:

{
  "success": true,
  "message": "OK",
  "data": {
    "filters": { "from": "2024-01-01", "to": "2024-01-31" },
    "section": "trends",
    "trends": {
      "clicks": 12.5,
      "conversions": -3.2,
      "revenue": 8.1
    }
  }
}

charts — Time-Series & Breakdown Data

Returns chart-ready data in { labels: [], data: [] } format, suitable for rendering line/bar/pie charts.

Available metrics:

Metric	Shape	Description
clicks_over_time	{labels, data}	Daily click counts
pageviews_over_time	{labels, data}	Daily pageview counts
device_breakdown	{labels, data}	Clicks by device type (desktop/mobile/tablet)
conversions_over_time	{labels, data}	Daily conversion counts
revenue_over_time	{labels, data}	Daily revenue totals
product_views_over_time	{labels, data}	Daily product view counts
add_to_carts_over_time	{labels, data}	Daily add-to-cart counts
country_breakdown	{labels, data}	Clicks by country
browser_breakdown	{labels, data}	Clicks by browser
os_breakdown	{labels, data}	Clicks by operating system
traffic_source_breakdown	{labels, data}	Clicks by traffic source

Example response:

{
  "success": true,
  "message": "OK",
  "data": {
    "filters": { "from": "2024-01-01", "to": "2024-01-07" },
    "section": "charts",
    "charts": {
      "clicks_over_time": {
        "labels": ["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05", "2024-01-06", "2024-01-07"],
        "data": [120, 145, 98, 201, 176, 133, 158]
      },
      "device_breakdown": {
        "labels": ["desktop", "mobile", "tablet"],
        "data": [612, 389, 30]
      }
    }
  }
}

tables — Ranked Tables

Returns top-N lists with associated metrics. Use top_limit to control how many rows are returned (default 10, max 50).

Available metrics:

Metric	Description
top_pages	Top landing pages by traffic
top_tracking_codes	Top affiliate tracking codes by clicks/conversions
top_affiliates	Top affiliates by performance
top_products	Top products by views/conversions

Example response:

{
  "success": true,
  "message": "OK",
  "data": {
    "filters": { "from": "2024-01-01", "to": "2024-01-31" },
    "section": "tables",
    "tables": {
      "top_affiliates": [
        { "name": "Jane Smith", "clicks": 420, "conversions": 18, "revenue": 2340.00 }
      ],
      "top_products": [
        { "product_id": "prod_abc", "name": "Widget Pro", "views": 312, "conversions": 24 }
      ]
    }
  }
}

recent_clicks — Paginated Click Feed

Returns a paginated list of recent click events. No metrics filtering applies. (Uses page and per_page query parameters)

Example response:

{
  "success": true,
  "message": "OK",
  "data": {
    "filters": { "from": "2024-01-01", "to": "2024-01-31" },
    "section": "recent_clicks",
    "recent_clicks": {
      "data": [
        {
          "id": 9812,
          "tracking_code": "AFF-JANE-001",
          "referrer_url": "https://blog.example.com/review",
          "page_url": "https://shop.example.com/product",
          "device": "mobile",
          "country": "US",
          "created_at": "2024-01-15T14:23:11Z"
        }
      ],
      "pagination": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 20,
        "total": 92
      }
    }
  }
}

recent_conversions — Paginated Conversion Feed

Returns a paginated list of recent conversion events. (Uses page and per_page query parameters)

Example response:

{
  "success": true,
  "message": "OK",
  "data": {
    "filters": { "from": "2024-01-01", "to": "2024-01-31" },
    "section": "recent_conversions",
    "recent_conversions": {
      "data": [
        {
          "id": 441,
          "order_id": "ORD-20240115-0042",
          "order_total": "149.99",
          "commission": "22.50",
          "tracking_code": "AFF-JANE-001",
          "currency": "USD",
          "created_at": "2024-01-15T16:05:33Z"
        }
      ],
      "pagination": {
        "current_page": 1,
        "last_page": 4,
        "per_page": 10,
        "total": 37
      }
    }
  }
}

recent_events — Paginated Event Feed

Returns a paginated list of all recent tracking events (clicks, pageviews, e-commerce events). Response structure mirrors recent_clicks and recent_conversions.

Using the metrics Parameter

For sections that support it (stats, trends, charts, tables), you can request only specific metrics to reduce response payload:

GET /v1/affiliate/analytics?section=stats&metrics=total_clicks,total_revenue,conversion_rate

• Pass a comma-separated list of metric names.
• Invalid metric names for the given section return a 422 validation error.
• Omit metrics entirely to receive all available metrics for the section.

Error Reference

HTTP Status	Error Code	Cause
401	UNAUTHORIZED	Missing or invalid Bearer token
403	FORBIDDEN	Token lacks reports:read scope
422	VALIDATION_ERROR	Invalid section, invalid metrics for section, or bad date range
500	—	Internal server error while building analytics data

Invalid section or metric (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "metrics": ["Invalid metric(s) for stats: clicks. Allowed: total_clicks, total_pageviews, ..."]
    }
  }
}

Missing/invalid token (401)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

Rate Limiting

This endpoint is throttled at 120 requests per minute per token. Exceeding the limit returns HTTP 429 Too Many Requests.