Skip to content
Cobalz Affiliate

REST API v1

The public REST API is at https://affiliate.cobalz.com/api/v1. The OpenAPI 3.1 spec is served live at /api/v1/openapi and is regenerated on every deploy.

Authentication

Every request needs a bearer token created in the dashboard at Settings → API keys. Keys are prefixed cob_ and shown exactly once at creation.

curl https://affiliate.cobalz.com/api/v1/affiliates \
  -H "Authorization: Bearer cob_xxx"

Scopes

  • read — list / get on every resource.
  • write — create + update (currently: POST /affiliates, POST /events).

Rate limits

Each key is rate-limited per rate_limit_per_min (default 600 req/min). Over-limit responses are HTTP 429 with a Retry-After header.

Plan gates

API access requires the Growth plan or above. Free / Starter merchants get the dashboard but no API key creation. If your merchant downgrades, existing keys return HTTP 402 PLAN_REQUIRED.

Endpoints

List affiliates

GET /api/v1/affiliates?status=approved&limit=50&offset=0

200 OK
{
  "data": [{"id": "...", "slug": "alice", "email": "alice@example.com",
            "status": "approved", "tier_id": null,
            "lifetime_commissions_paid": 240.50, ...}],
  "has_more": true,
  "limit": 50,
  "offset": 0
}

Get an affiliate

GET /api/v1/affiliates/<affiliate_id>

200 OK
{"id": "...", "slug": "alice", ... }
Note:Sensitive fields like tin_vault_id, fingerprint_visitor_ids, and payout_details_vault_id are not exposed via the API. If your team needs them, fetch directly through Supabase with the service role.

Create an affiliate

POST /api/v1/affiliates
Content-Type: application/json

{
  "email": "bob@example.com",
  "slug": "bob",
  "display_name": "Bob",
  "parent_email": "alice@example.com"  // optional, MLM
}

201 Created
{"id": "...", ...}

List commissions

GET /api/v1/commissions?affiliate_id=...&status=approved&from=2024-01-01

200 OK
{"data": [{"id": "...", "amount": 12.50, "currency": "USD",
           "status": "approved", "order_id": "...", ...}], ...}

Track a conversion event

Use this for non-WooCommerce / non-Shopify integrations. The event is matched against the affiliate's referral cookie or coupon.

POST /api/v1/events
Content-Type: application/json

{
  "cookie_id": "<from _cobz_sess cookie>",
  "type": "purchase",
  "amount": 99.00,
  "currency": "USD",
  "external_id": "your-order-id",
  "metadata": {"sku": "WIDGET-1"}
}

Error shape

{
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "API access requires the Growth plan or above."
  }
}

Common codes: UNAUTHORIZED, FORBIDDEN, PLAN_REQUIRED, RATE_LIMITED, INVALID_INPUT, NOT_FOUND.

Client SDKs

  • TypeScript — first-class, generated from OpenAPI. npm i @cobalz/sdk. Source.
  • PHP — scaffold included in the repo at packages/sdk-php.
  • Python — scaffold included at packages/sdk-python.