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

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.):

Example request & response:

curl "api.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:

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:

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:

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

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.