HeldSway

Affiliate Analytics API

The Analytics Query endpoint provides flexible, multi-dimensional reporting across aggregate headline metrics, growth trends, time-series charts, top-ranking breakdown tables, and real-time activity streams.

Endpoint Overview

GET /v1/affiliate/analytics
Authorization: Bearer <access_token>
  • Required Scope: reports:read
  • Base URL: https://api.heldsway.com/api/v1/affiliate/analytics
  • Rate Limit: 120 requests/minute
  • Subscription Gate: Requires active subscription

Query Parameters

Parameter Type Required Default Constraints Description
section string No stats stats, trends, charts, tables, recent_clicks, recent_conversions, recent_events The analytics section to compute
from date No 30 days ago YYYY-MM-DD Start of date range (inclusive)
to date No Today YYYY-MM-DD End of date range (inclusive)
metrics string No All metrics Comma-separated Filter specific metrics (e.g. total_clicks,total_revenue)
top_limit integer No 5 1–50 Maximum number of rows returned for the tables section
page integer No 1 min:1 Page number (for recent_* sections)
per_page integer No 15 1–100 Items per page (for recent_* sections)
location_id string No — max:64 Filter metrics by store location ID
source_domain string No — max:255 Filter metrics by storefront origin domain

Analytics Sections

1. section=stats (Aggregate Totals)

Returns scalar numeric totals across the selected date range:

Metric Type Description
total_clicks integer Total affiliate referral link clicks
total_pageviews integer Total pageviews tracked by the SDK
unique_visitors integer Count of distinct visitor sessions
pages_per_visit float Average pages viewed per visitor session
total_conversions integer Count of tracked orders
total_revenue float Gross order revenue attributed to affiliates
total_commission float Total affiliate commission earned
conversion_rate float Percentage of clicks resulting in conversions
total_product_views integer Product detail page views
total_add_to_carts integer Cart addition events
total_remove_from_carts integer Items removed from cart
total_thank_you_views integer Order confirmation pageviews
cart_to_conversion_rate float Percentage of cart sessions that converted

Example Request

curl -X GET "https://api.heldsway.com/api/v1/affiliate/analytics?section=stats&from=2026-03-01&to=2026-03-31" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

Success Response — HTTP 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "filters": {
      "from": "2026-03-01",
      "to": "2026-03-31",
      "location_id": null,
      "source_domain": null
    },
    "section": "stats",
    "stats": {
      "total_clicks": 4200,
      "total_pageviews": 12850,
      "unique_visitors": 3100,
      "pages_per_visit": 4.1,
      "total_conversions": 142,
      "total_revenue": 18450.00,
      "total_commission": 1845.00,
      "conversion_rate": 3.38,
      "total_product_views": 6200,
      "total_add_to_carts": 510,
      "total_remove_from_carts": 85,
      "total_thank_you_views": 142,
      "cart_to_conversion_rate": 27.84
    }
  }
}

2. section=trends (Growth Percentages)

Computes percentage growth compared against the previous equal period:

{
  "success": true,
  "message": "OK",
  "data": {
    "section": "trends",
    "trends": {
      "clicks": 14.5,
      "pageviews": 8.2,
      "visitors": 12.0,
      "conversions": 25.4,
      "revenue": 31.8,
      "commission": 28.5,
      "product_views": 5.4,
      "add_to_carts": 18.2
    }
  }
}

3. section=charts (Time-Series & Breakdowns)

Returns formatted chart datasets containing labels and corresponding series data:

  • clicks_over_time
  • pageviews_over_time
  • conversions_over_time
  • revenue_over_time
  • device_breakdown (Desktop, Mobile, Tablet)
  • traffic_source_breakdown (Direct, Referral, Organic, Social)
  • country_breakdown

4. section=tables (Leaderboards & Rankings)

Returns top-performing entities ranked by volume or revenue:

  • top_affiliates: Affiliates ranked by generated revenue.
  • top_tracking_codes: Best-converting referral slugs.
  • top_pages: Most visited landing and product pages.
  • top_products: Products with the highest attributed conversion volume.

5. section=recent_clicks & section=recent_conversions (Activity Streams)

Returns a paginated stream of real-time events:

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "id": 14209,
        "type": "conversion",
        "order_id": "ORD-88129",
        "affiliate_name": "Jane Smith",
        "amount": 149.99,
        "commission": 15.00,
        "created_at": "2026-04-18T10:15:20.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 15,
      "total": 340
    }
  }
}

Error Responses

HTTP Status Error Code Description
401 UNAUTHORIZED Missing or invalid Bearer token
402 SUBSCRIPTION_REQUIRED An active plan is required to query analytics
403 FORBIDDEN Token lacks reports:read scope
422 VALIDATION_FAILED Invalid date format or unsupported section parameter
429 TOO_MANY_REQUESTS Exceeded 120 requests/minute rate limit
← Orders & CommissionsAffiliate Reports →