Skip to content
Cobalz Affiliate

REST API v1

An affiliate API your engineers will actually like.

OpenAPI 3.1 spec. Bearer cob_* tokens with scopes. Cursor pagination. Per-key rate limiting. Standard Webhooks v1 outbound. Built like a 2026 SaaS API, not a 2014 affiliate plugin export.

What you can do

Affiliates, commissions, events.

  • Yes List + filter affiliates (status, cursor)
  • Yes Get an affiliate by id
  • Yes Create affiliates (with parent_email for MLM lineage)
  • Yes List commissions (status, affiliate, cursor)
  • Yes POST /events for non-order conversions (leads, trials, signups)
  • Yes All endpoints respect RLS — your API key only sees your merchant's rows

Full spec at /api/v1/openapi. Generate clients with openapi-generator-cli.

# Track a SaaS trial as a conversion event
curl https://affiliate.cobalz.com/api/v1/events \
  -H "Authorization: Bearer cob_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "trial_started",
    "external_id": "stripe_sub_abc",
    "cookie_id": "$_cobz_sess",
    "amount": 0,
    "currency": "USD",
    "payload": { "plan": "growth" }
  }'

# List approved commissions, paginated
curl "https://affiliate.cobalz.com/api/v1/commissions?status=approved&limit=100" \
  -H "Authorization: Bearer cob_xxx"

# Create an affiliate via API (e.g. from your CMS)
curl https://affiliate.cobalz.com/api/v1/affiliates \
  -H "Authorization: Bearer cob_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "display_name": "Alice Chen",
    "slug": "alice-chen",
    "status": "approved",
    "custom_commission_rate": 0.20
  }'

Outbound webhooks

Standard Webhooks v1.

Cobalz signs every outbound webhook with the Standard Webhooks v1.0.2 spec: webhook-id, webhook-timestamp, webhook-signature (HMAC-SHA256, base64, v1,... prefixed). Drop in svix-libsfor instant verification.

// Verify with svix-libs (one of many SDKs)
import { Webhook } from 'svix';

app.post('/webhooks/cobalz', (req, res) => {
  const wh = new Webhook(process.env.COBALZ_SECRET);
  try {
    const evt = wh.verify(req.rawBody, req.headers);
    // evt.type === 'commission.approved' etc.
  } catch {
    return res.status(401).send();
  }
  res.status(200).send();
});

Event types

  • affiliate.approved
  • affiliate.suspended
  • affiliate.tier_promoted
  • commission.created
  • commission.approved
  • commission.voided
  • payout.sent
  • payout.paid
  • fraud.flagged
  • tax_form.submitted

Backoff schedule: 5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h. Max 10 attempts. 410 → endpoint auto-disabled. Replay UI in dashboard.

FAQ

API + webhook questions.

Where do I get an API key?+
Settings → API keys in your dashboard. Generate as many as you need with read-only / write / wildcard scopes. Each key shows a prefix (cob_…) plus an audit log. Revoke anytime.
Is there a rate limit?+
Yes. Default 600 requests/minute per API key, backed by Upstash Redis. 429 with Retry-After header on hit. Configurable per key on Scale+ plans.
Pagination?+
Cursor-based — pass ?cursor= back from each page's next_cursor. No offset/limit, no integer page numbers, no skipped rows on insert.
Is the API on every plan?+
Available on Growth and up. Free + Starter plans get the dashboard + webhooks but not the REST API.

Build it the way you want it.

REST + webhooks included on Growth plans and up.

Start free trialOpenAPI spec