Skip to main content

REST API Endpoint Reference

Source-aligned /api/v1 endpoints, query params, request fields, and error codes

Table of Contents

REST API Endpoint Reference

Reference for currently exposed /api/v1 endpoints.

Global Contract

  • Auth (one of): Authorization: Bearer <API_KEY>, Authorization: Basic <base64(API_KEY:)>, X-Api-Key: <API_KEY>
  • Account context (required): ?account_id=<ACCOUNT_ID> or X-Account-Id: <ACCOUNT_ID>
  • Pagination defaults: page=1, limit=25, max limit=100
  • Array params: state[]=due&state[]=pending or state=due,pending
  • Expand params: expand[]=campaign&expand[]=sale or expand=campaign,sale
  • Timestamp filters (updated_since, updated_until) must be ISO-8601 where supported

Common error envelope:

{
  "error": "Account ID is required",
  "code": "MISSING_ACCOUNT_ID"
}

Common error codes: MISSING_ACCOUNT_ID, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR

Plans

  • GET /api/v1/plans
    • Query:
      • interval (month|monthly|year|annual, optional)
    • Response shape:
      • { "plans": [...] }

Subscription

  • GET /api/v1/subscription
    • Response shape:
      • { "subscription": { ... } | null, "billing": { ... } }
  • PATCH /api/v1/subscription
    • Body:
      • plan_id (required for plan changes)
      • billing_interval (optional)
      • billing_cycle_anchor (optional)
      • proration_behavior (optional)
  • POST /api/v1/subscription/cancel
    • Body:
      • at_period_end (boolean, optional)
  • POST /api/v1/subscription/pause
  • POST /api/v1/subscription/resume

API Keys

  • GET /api/v1/api_keys
    • Query: page, limit
    • Role (session auth): owner or admin
  • POST /api/v1/api_keys
    • Body:
      • name (string, required)
      • permissions (object, optional)
      • expires_at (ISO datetime, optional)
    • Notes:
      • permissions must be an object.
      • If omitted, key defaults to full access ({ "all": true }).
    • Role (session auth): owner or admin
  • DELETE /api/v1/api_keys/:id
    • Revokes key (does not hard-delete row)
    • Returns success message JSON
    • Role (session auth): owner or admin

Affiliates

  • GET /api/v1/affiliates
    • Query:
      • page, limit
      • campaign_id
      • email
      • state or state[] (pending|active|disabled|suspicious|rejected)
      • stripe_customer_id
      • updated_since, updated_until (ISO-8601)
      • expand[] (campaign, links, coupon, commission_stats)
  • POST /api/v1/affiliates
    • Body:
      • email (required)
      • campaign_id (optional if account has an active default campaign)
      • first_name, last_name (optional)
      • state (optional, defaults to active)
      • paypal_email, wise_email (optional)
  • GET /api/v1/affiliates/:id
    • Query: expand[] (campaign, links, coupon, commission_stats)
  • PATCH /api/v1/affiliates/:id
    • Body:
      • state
      • campaign_id
      • paypal_email
      • wise_email
  • DELETE /api/v1/affiliates/:id
    • Archives by default
    • Returns 204 No Content

Affiliate Coupons

  • GET /api/v1/affiliates/:affiliate_id/coupon
  • POST /api/v1/affiliates/:affiliate_id/coupon
  • PATCH /api/v1/affiliates/:affiliate_id/coupon
  • DELETE /api/v1/affiliates/:affiliate_id/coupon
    • Returns 204 No Content
  • POST /api/v1/affiliates/:affiliate_id/coupon/sync
    • Body:
      • force (boolean, optional)

Campaigns

  • GET /api/v1/campaigns
    • Query: page, limit
  • POST /api/v1/campaigns
  • PATCH /api/v1/campaigns/:id
    • Body fields (partial updates supported):
      • name, slug, url
      • private, private_tokens
      • reward_type (percent|fixed)
      • commission_percent
      • commission_amount_cents, commission_amount_currency
      • minimum_payout_cents, minimum_payout_currency
      • max_commission_period_months, max_commissions
      • days_before_referrals_expire, days_until_commissions_are_due
      • affiliate_dashboard_text, custom_reward_description, welcome_text
      • customers_visible_to_affiliates, sale_description_visible_to_affiliates
      • parameter_type
      • stripe_coupon_id
      • default
  • GET /api/v1/campaigns/:id
  • DELETE /api/v1/campaigns/:id
    • Archives by default
    • Returns 204 No Content
  • GET /api/v1/links
    • Query:
      • affiliate_id
      • campaign_id
      • page, limit
  • POST /api/v1/links
    • Body:
      • affiliate_id (required)
      • campaign_id (required)
      • url (required)
      • token (optional; auto-generated if missing)
  • GET /api/v1/links/:id
  • PATCH /api/v1/links/:id
    • Body: affiliate_id, campaign_id, url, token
  • DELETE /api/v1/links/:id
    • Archives by default
    • Returns 204 No Content

Referrals

  • GET /api/v1/referrals
    • Query:
      • page, limit
      • affiliate_id
      • conversion_state or conversionState
      • stripe_customer_id
      • email (customer email)
      • updated_since, updated_until (ISO-8601)
      • expand[] (link, customer, affiliate)
  • POST /api/v1/referrals
    • Body:
      • affiliate_id (required)
      • campaign_id (required when link_id is omitted)
      • link_id (optional)
      • conversion_state (visitor|lead|conversion, optional)
      • expires_at (ISO datetime, optional)
  • GET /api/v1/referrals/:id
    • Query: expand[] (link, customer, affiliate)
  • PATCH /api/v1/referrals/:id
    • Body:
      • conversion_state (visitor|lead|conversion)
      • deactivated_at (ISO datetime or null)
      • customer_email (optional; binds/creates customer)
  • DELETE /api/v1/referrals/:id
    • Soft-deactivates referral
    • Returns 204 No Content

Commissions

  • GET /api/v1/commissions
    • Query:
      • page, limit
      • state or state[]
      • affiliate_id
      • campaign_id
      • updated_since, updated_until (ISO-8601)
      • expand[] (campaign, sale)
  • GET /api/v1/commissions/:id
  • PATCH /api/v1/commissions/:id
    • Body:
      • due_at (ISO datetime, optional)
      • paid_at (ISO datetime or null)
    • Notes:
      • Setting paid_at sets state to paid
      • Clearing paid_at recalculates pending|due
      • Updating paid state for voided commissions is rejected
  • DELETE /api/v1/commissions/:id
    • Soft-voids commission
    • Body:
      • void_reason (optional)
  • POST /api/v1/commissions/:id/review
    • Body:
      • review_action (approve|suspicious|deactivate)

Payouts

  • GET /api/v1/payouts
    • Query:
      • page, limit
      • affiliate_id
      • state or state[]
      • eligible=true (returns eligible payout candidates; non-paginated)
      • updated_since, updated_until (ISO-8601)
      • expand[] (affiliate, commissions)
  • GET /api/v1/payouts/:id
  • POST /api/v1/payouts/:id/pay
    • Body:
      • payment_reference (optional)

Payout Exports

  • GET /api/v1/payout_exports
    • Query:
      • limit
  • POST /api/v1/payout_exports
    • Body:
      • payout_ids (array, optional)
      • export_format (csv|paypal|wise, optional)
      • notes (optional)
  • GET /api/v1/payout_exports/:id
    • Query:
      • export_format (csv|paypal|wise, optional)
    • Notes:
      • Returns metadata plus filename and content
  • DELETE /api/v1/payout_exports/:id
  • POST /api/v1/payout_exports/:payout_export_id/payment
    • Body:
      • payment_reference (optional)

Payout Runs

  • POST /api/v1/payout_runs
    • Body:
      • idempotency_key (optional; generated if omitted)
      • execute_now (boolean, optional, default false)
      • affiliate_ids (array, optional)
      • payment_reference (optional; used when execute_now=true)
  • PUT /api/v1/payout_runs/:id/execute
    • Body:
      • async (boolean, optional, default true)
      • payment_reference (optional)
  • PUT /api/v1/payout_runs/:id/remediate
    • Body:
      • remediation_action (required)
      • issue_code (optional)
      • payout_ids (array, optional)
  • GET /api/v1/payout_runs/reconcile
    • Query:
      • lookback_days (optional, default 30)

Invitations

  • GET /api/v1/invitations
    • Query:
      • kind (member|affiliate, optional)
      • status (pending|accepted|revoked, optional)
      • page, limit
  • POST /api/v1/invitations
    • Body:
      • kind (member|affiliate, required)
      • email (required)
      • role (for member, optional, defaults to member)
      • campaign_id or campaignId (for affiliate, required)
  • GET /api/v1/invitations/:id
    • Query:
      • kind (optional but recommended)
  • PATCH /api/v1/invitations/:id
    • Body:
      • kind (optional but recommended)
      • invitation_action or status_action (accept|revoke)
      • status=revoked (alias for revoke)
      • role (member-invitation role update path)
      • user_id (optional for API-key acceptance path)
  • DELETE /api/v1/invitations/:id
    • Query/body:
      • kind (optional but recommended)
    • Returns 204 No Content
  • POST /api/v1/invitations/:id/resend
    • Query/body:
      • kind (optional but recommended)

LLM/SDK Integration Tip

Use the machine-readable contract when generating clients:

Example Request

curl "https://app.affiliatebase.io/api/v1/commissions?account_id=<ACCOUNT_ID>&state=due&expand=campaign,sale&page=1&limit=25" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json"