Stats API

Read clicks, conversions and revenue for your affiliate programs and conversion links over any period.

Emil Klitmose

Written by Emil Klitmose

Updated recently

Overview

The Stats API is a read-only, server-to-server REST endpoint for pulling your program analytics into spreadsheets, dashboards, or your own reporting. It returns the same numbers you see on your dashboard: clicks, conversions (sales plus qualified leads), and revenue, split into affiliate programs and conversion links.

Base URL: https://www.revshare.so/api/v1

Manage your key and try live requests in Dashboard → API.

Authentication

Send your secret API key in the x-api-key header (a Authorization: Bearer <key> header is also accepted). It's the same key used for the Referral API — find it in Dashboard → API.

x-api-key: rs_your_secret_key

Keep it secret. The key grants read access to all your program analytics. These endpoints send no CORS headers — always call them from your backend, never from browser code.

Rate Limits

Requests are limited to 60 per minute per API key. Every response includes the current window in its headers:

X-RateLimit-Limit // 60

X-RateLimit-Remaining // requests left this minute

When you exceed the limit you'll get a 429 Too Many Requests with a Retry-After header (seconds to wait).

GET /v1/stats

Returns aggregated stats for the authenticated account over a period. All query parameters are optional.

Endpoint: GET https://www.revshare.so/api/v1/stats

Header: x-api-key: YOUR_API_KEY

Parameters

period string, optional — One of 24h, 7d, 30d, 90d, all. Defaults to 30d.

from ISO date, optional — Start of a custom window (e.g. 2026-06-01). Overrides period.

to ISO date, optional — End of a custom window. Defaults to now when only from is given.

type string, optional — Narrow the result to affiliate or conversion (default all).

program_id string, optional — Restrict the result to a single program.

Response

200 OK with a JSON body. Revenue is returned as a revenue_by_currency map — integer cents keyed by the actual currency of each conversion — so multi-currency programs aren't collapsed into one total. conversions = sales + leads.

{
  "period": {
    "label": "30d",
    "from": "2026-05-19T12:00:00.000Z",
    "to": "2026-06-18T12:00:00.000Z"
  },
  "totals": {
    "programs": 3,
    "clicks": 1842,
    "conversions": 57,
    "sales": 51,
    "leads": 6,
    "revenue_by_currency": { "USD": 1100000, "EUR": 189900 },
    "currencies": ["EUR", "USD"]
  },
  "affiliate_programs": {
    "programs": 2,
    "clicks": 1500,
    "conversions": 40,
    "sales": 40,
    "leads": 0,
    "revenue_by_currency": { "USD": 1100000 }
  },
  "conversion_links": {
    "programs": 1,
    "clicks": 342,
    "conversions": 17,
    "sales": 11,
    "leads": 6,
    "revenue_by_currency": { "EUR": 189900 }
  },
  "programs": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "name": "Acme Pro",
      "slug": "acme-pro",
      "type": "affiliate",
      "program_currency": "USD",
      "clicks": 1200,
      "conversions": 32,
      "sales": 32,
      "leads": 0,
      "revenue_by_currency": { "USD": 900000 }
    }
  ]
}

Field notes

type string — affiliate for standard programs, conversion for conversion-tracking links.

revenue_by_currency object — Cents keyed by the transaction currency, e.g. { "USD": 900000, "EUR": 12000 } ($9,000.00 + €120.00). Excludes refunded and disputed sales.

program_currency string — The program's configured currency (informational). Actual revenue uses each conversion's own currency.

conversions integer — Number of conversions — sales plus qualified (non-rejected) leads.

currencies string[] — Sorted list of currencies present in totals.revenue_by_currency.

Examples

Last 7 days, all programs:

curl "https://www.revshare.so/api/v1/stats?period=7d" \
  -H "x-api-key: $REVSHARE_API_KEY"

Conversion links only, custom date range:

curl "https://www.revshare.so/api/v1/stats?type=conversion&from=2026-01-01&to=2026-03-31" \
  -H "x-api-key: $REVSHARE_API_KEY"

In JavaScript (Node):

const res = await fetch(
  "https://www.revshare.so/api/v1/stats?period=30d",
  { headers: { "x-api-key": process.env.REVSHARE_API_KEY } }
);

if (!res.ok) throw new Error(`Stats API ${res.status}`);

const { totals, affiliate_programs, conversion_links } = await res.json();
console.log("Conversions:", totals.conversions);
console.log("Revenue by currency:", totals.revenue_by_currency);

GET /v1/invoices

Lists your Revshare invoices (plan subscriptions and platform fees), newest first. Use it to pull invoices into your bookkeeping. Same API key and rate limit as the stats endpoint.

limit number — 1–100, default 50.

starting_after string — The previous page's next_cursor, to read the next page.

Each invoice has id, number, status, currency, total and amount_paid (in cents), created, paid_at and pdf_url. Download the PDF from GET /v1/invoices/{id}/pdf with the same key.

curl "https://www.revshare.so/api/v1/invoices?limit=20" \
  -H "x-api-key: $REVSHARE_API_KEY"

curl "https://www.revshare.so/api/v1/invoices/in_123/pdf" \
  -H "x-api-key: $REVSHARE_API_KEY" -o invoice.pdf

Errors

Errors return a JSON body of the shape { "error": "message" } with the appropriate status code:

400 Bad Request — Invalid parameter (e.g. bad period or date).

401 Unauthorized — Missing or invalid API key.

404 Not Found — The invoice doesn't exist or isn't yours.

429 Too Many Requests — Rate limit exceeded — see Retry-After.

500 Server Error — Something went wrong on our side.

Prefer to explore interactively? Open Dashboard → API and use the live preview to run real requests against your account.