Skip to main content
AffiliateBase
Features Pricing Compare Help
Log in Start for free

REST API Endpoint Reference

Reference AffiliateBase REST API endpoints, account-scoped query parameters, request fields, response shapes, and error codes.

Table of Contents

Use this reference to choose the current /api/v1 endpoint, parameters, and response contract for an AffiliateBase integration.

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

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
    • Returns the commission object directly, not wrapped in data.
    • Includes expanded campaign and sale data.
    • The expanded sale includes referral, customer, and affiliate details when present.
    • Common enrichment fields:
      • sale.referral.customer.email
      • sale.referral.customer.name
      • sale.referral.stripe_customer_id
      • sale.affiliate.id
      • sale.affiliate.email
      • sale.affiliate.first_name
      • sale.affiliate.last_name
  • 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"

Individually assigned promo codes

These endpoints let you manage individually assigned Stripe promo codes. Stripe operations require a connected Stripe account and an active affiliate in an active campaign. They use the existing v1.affiliate_coupons.read and v1.affiliate_coupons.write API permissions.

EndpointBehavior
GET /api/v1/affiliates/:affiliate_id/promo_codesList assignments; use q for exact Stripe code search or discounts=true for valid discounts.
POST /api/v1/affiliates/:affiliate_id/promo_codesPreview/import an exact stripe_promotion_code_id, or use mode=create, code and stripe_coupon_id.
PATCH /api/v1/affiliates/:affiliate_id/promo_codes/:idPreview or persist the current provider observation.
DELETE /api/v1/affiliates/:affiliate_id/promo_codes/:idPreview or stop tracking locally, keeping Stripe redemption and historical records intact.

Writes default to dry_run=true. Execute using dry_run=false; import and creation also require a stable Idempotency-Key. Reuse that key with the same payload after an uncertain response. OPERATION_PENDING requires checking the original result; RECONCILIATION_REQUIRED requires review before another creation attempt. An assignment response is not paid-attribution proof.

Display code to customers. tracking_token is an opaque compatibility identifier. Ownership uses the exact provider ID, account and live/test mode. Codes cannot be transferred or reactivated through this release. The existing singular /coupon endpoint remains the legacy campaign default.

The affiliate_promo_codes MCP tool exposes the same operations and defaults to preview. A connector needs explicit mcp.affiliate_coupons.read / mcp.affiliate_coupons.write permissions. New connector creation offers an optional Allow promo-code management checkbox; existing tokens keep their current permissions.

See Manage Promo Codes with MCP for copyable tool calls, permission setup and retry guidance, or Assign Stripe Promo Codes to Affiliates for the merchant workflow.