API Reference
.mdJSON

Affiliatops API

Affiliate and referral tracking for e-commerce, SaaS and service businesses.

The API is organized around five surfaces:

•Tracking (/api/track/*) — called from your website or app with a store public key. Records clicks, conversions, sign-ups and analytics events.

•SaaS (/api/saas/events, Stripe webhook) — server-to-server subscription and billing events that drive recurring partner commissions.

•Webhooks (/api/webhook/*) — server-to-server receivers for conversions and refunds, authenticated with an API key or an HMAC signature.

•Affiliate (/api/affiliate/*) — the partner portal, authenticated with a session cookie.

•Admin (/api/admin/*) — the merchant dashboard, authenticated with a session cookie. All data is automatically scoped to the caller’s merchant.

Conventions

•Money is stored and returned in integer minor units (amountCents, amount_cents): 150000 = Rp 1.500 / $1,500.00. Some inputs also accept amount in major units — each field says which.

•The platform is multi-tenant: admin endpoints only ever read or write rows belonging to the authenticated merchant.

•Timestamps are ISO-8601 strings (UTC).

•Errors return { "error": string } or { "success": false, "message": string } with a 4xx/5xx status.

•Default market is Indonesia (ID / IDR).

For AI agents

•/docs/agent.md is this reference as one Markdown file, with integration recipes. /api/docs is the raw OpenAPI JSON.

License: MIT · [email protected]

Integrating with an AI coding agent?

Give it /docs/agent.md: one Markdown file with credentials, conventions, step-by-step recipes and every integration endpoint.

Open

Authentication

Add the keys you want to test with. They stay in this browser tab (session storage) and are only sent to https://affiliatops.com when you press Send in a Try it panel.

SessionCookiecookie: auth-token

Browser session. Obtain it via POST /api/auth/login (or verify-otp), which sets an httpOnly auth-token JWT cookie. Used by all /api/affiliate/* and /api/admin/* endpoints.

Only sent to this site. Switch the server back to use it.

ApiKeyAuthheader: X-API-Key

Store public key (pk_store_…) for /api/track/*. Safe to ship in browser code, so server endpoints reject it. Create one under Admin → Store integrations.

Sent as X-API-Key to /api/track/*.

ServerKeyAuthheader: Authorization: Bearer

Server secret for /api/saas/events and /api/webhook/*: a store integration secret key (sk_store_…, shown once when the integration is created) or a merchant API key (aft_…; /api/saas/events needs write scope). Never expose it in a browser.

For /api/saas/events (API keys need write scope) and /api/webhook/*. Sent as a Bearer token or X-API-Key, depending on the option you pick.

ServerKeyHeaderheader: X-API-Key

Alternative to the bearer header for /api/saas/events and /api/webhook/*. Same server secret; public keys (pk_…) are rejected.

Uses the same key as ServerKeyAuth.

WebhookSignatureheader: X-Webhook-Signature

HMAC-SHA256 of the raw request body using WEBHOOK_SECRET, hex-encoded (an optional sha256= prefix is accepted). Alternative auth for /api/webhook/*.

Signs the request in your browser. The secret itself is never sent.

StripeSignatureheader: Stripe-Signature

Sent by Stripe: t=<unix>,v1=<HMAC-SHA256 of "<t>.<raw body>" keyed with the endpoint signing secret (whsec_…)>. Save the signing secret on the Stripe integration.

Signs a Stripe-Signature header in your browser. The secret itself is never sent.

CronSecretheader: X-Cron-Secret

Shared secret (CRON_SECRET) for unattended jobs such as commission maturation.

Sent as X-Cron-Secret.

Auth

Login, registration, OTP and session handling.

Tracking

Public storefront tracking — clicks, conversions and analytics events. Authenticated with a store API key (X-API-Key).

Webhooks

Server-to-server event receivers. Authenticated with an API key or an HMAC signature.

SaaS

Subscription lifecycle and billing events for SaaS workspaces: sign-ups, trials, subscriptions, payments and refunds. Drives recurring partner commissions.

Affiliate

Partner portal endpoints, including the SaaS partner dashboard. Authenticated with the session cookie.

SaaS (Admin)

SaaS workspace: KPIs and metrics, referred customers and subscriptions, plans, the recurring commission plan, integrations and the billing-event ledger.

Affiliates (Admin)

Manage partner accounts and their status.

Referrals (Admin)

Review, approve and reject referral leads.

Commissions (Admin)

Commission ledger, maturation and commission rules.

Payouts (Admin)

Create, complete and automate affiliate payouts; invoices, transactions and refunds.

Programs (Admin)

Programs, program settings, partner groups and coupons.

Analytics (Admin)

Dashboards, detailed analytics, live sessions and reports.

Integrations (Admin)

Store integrations, API keys, usage and outbound webhooks.

Team (Admin)

Merchant profile, workspace mode and onboarding, team members and merchant switching.

System

Health and status probes for uptime monitors and the deploy platform. Public.

Billing (Admin)

Your Affiliatops plan, billed through Stripe: checkout with the free trial, plan changes, cancellation, the Stripe customer portal, billing history, and the billing webhook. Needs STRIPE_SECRET_KEY (and STRIPE_WEBHOOK_SECRET for the webhook).

Schemas

Shared data models used across the API