Validate affiliate credentials. Returns affiliate identity for your system to issue its own session token.

Request Body

{
  "email": "affiliate@example.com",
  "password": "their-password"
}

Response

200 Success

{
  "affiliate": {
    "id": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
    "name": "Demo Affiliate",
    "email": "affiliate@example.com",
    "referralLink": "https://bluecarrental.is?ref=demo-affiliate",
    "bankAccount": {
      "holderName": "Demo Affiliate ehf.",
      "bankName": "Landsbankinn",
      "iban": "IS140159260076545510730339",
      "swift": "NBIIISRE"
    }
  }
}

The bankAccount field is always present in the response. It is null when the affiliate has not yet configured a bank account, allowing your system to render a "configure your account" CTA without an extra round-trip.

{
  "affiliate": {
    "id": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
    "name": "Demo Affiliate",
    "email": "affiliate@example.com",
    "referralLink": "https://bluecarrental.is?ref=demo-affiliate",
    "bankAccount": null
  }
}

400 Validation error (flat error shape)

{
  "error": "Email and password are required"
}

"Invalid request body" is also returned with 400 for malformed JSON.

401 Invalid credentials (flat error shape)

{
  "error": "Invalid credentials"
}

Submit a new affiliate application from the "Join Us" form. Creates an affiliate with status unapproved.

Request Body

{
  "email": "new-affiliate@example.com",
  "password": "securepassword123",
  "firstName": "John",
  "lastName": "Smith",
  "companyName": "Nordic Travel Co",
  "website": "https://nordictravel.co",
  "instagram": "@nordictravel",
  "tiktok": "",
  "youtube": "",
  "facebook": "nordictravel"
}

Parameters

Response

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug": "nordic-travel-co",
  "email": "new-affiliate@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "companyName": "Nordic Travel Co",
  "status": "unapproved",
  "availableBalance": 0,
  "carenSetupComplete": false,
  "createdAt": "2026-03-31T12:00:00Z",
  "updatedAt": "2026-03-31T12:00:00Z"
}

The full Affiliate record is returned. Optional fields (e.g. companyName, website, social handles) are omitted when empty; availableBalance, carenSetupComplete, status, createdAt, and updatedAt are always present.

400 Validation error (flat error shape)

{
  "error": "First name, last name, email, and password are required"
}

"Invalid request body" is also returned with 400 for malformed JSON.

409 Email already registered (flat error shape)

{
  "error": "An account with this email already exists"
}

500 Server error (flat error shape)

{
  "error": "Failed to process application"
}

Server error — safe to retry with backoff.

Record a referral link click. Call this whenever a visitor arrives via an affiliate's referral link.

Path Parameters

Request Body

All fields are optional and backward-compatible. Old clients that send only country and sourceApp continue to work unchanged.

{
  "country": "IS",
  "sourceApp": "website",
  "subId": "promo-spring",
  "source": "instagram",
  "medium": "social",
  "campaign": "spring-2026"
}

Parameters

Response

201 Created

{
  "status": "ok"
}

400 Invalid affiliate ID format (flat error shape)

{
  "error": "Invalid affiliate ID format"
}

404 Affiliate not found (flat error shape)

{
  "error": "Affiliate not found"
}

500 Failed to record click (flat error shape)

{
  "error": "Failed to record click"
}

Server error — safe to retry with backoff.

Get daily click counts for a date range. Every day in the range is included, even if the count is zero.

Query Parameters

Response

200 Success

{
  "clicksPerDay": [
    { "date": "2026-03-01", "value": 94 },
    { "date": "2026-03-02", "value": 87 },
    { "date": "2026-03-03", "value": 0 }
  ]
}

Each item's date is a calendar day in YYYY-MM-DD form — not an ISO timestamp — and value is the integer click count for that day.

400 Missing or invalid date range (flat error shape)

{
  "error": "from and to query parameters are required"
}

500 Server error (flat error shape)

{
  "error": "Failed to get daily clicks"
}

Server error — safe to retry with backoff.

Get the total click count for a date range.

Query Parameters

Response

200 Success

{
  "total": 1234
}

400 Missing or invalid date range (flat error shape)

500 Server error (flat error shape)

{
  "error": "Failed to get total clicks"
}

Server error — safe to retry with backoff.

Per-sub-id click breakdown for the affiliate's referral traffic. Use this to see how individual sub-affiliate identifiers and UTM combinations are performing.

Query Parameters

If both from and to are omitted, the endpoint defaults to the last 30 days (to = today UTC, from = today − 30 days). Supplying only one of the two still returns 400 — partial date ranges are not allowed, since one-sided defaults would silently widen a caller's query window.

Response

200 Success

[
  {
    "subId": "promo-spring",
    "source": "instagram",
    "medium": "social",
    "campaign": "spring-2026",
    "clicks": 142,
    "bookings": null,
    "conversionPercent": null,
    "revenue": null
  }
]

Rows are ordered by clicks DESC, then subId ASC for stable rendering. Clicks with a NULL sub_id are excluded. The source, medium, and campaign fields are taken from the most recent click's UTM tags for each sub-id.

400 Invalid date range (nested error shape)

{
  "error": {
    "message": "from and to query parameters are required"
  }
}

500 Server error (nested error shape)

{
  "error": {
    "message": "Failed to get sub-id performance"
  }
}

Server error — safe to retry with backoff.

Get total revenue generated through the affiliate's referral link for a date range.

Query Parameters

Response

200 Success

{
  "total": 45000
}

400 Missing or invalid date range (flat error shape)

500 Server error (flat error shape)

{
  "error": "Failed to get revenue"
}

Server error — safe to retry with backoff.

Get expected commission for a date range.

Query Parameters

Response

200 Success

{
  "total": 2250
}

400 Missing or invalid date range (flat error shape)

500 Server error (flat error shape)

{
  "error": "Failed to get commission"
}

Server error — safe to retry with backoff.

Get the affiliate's current available payout balance.

Response

200 Success

{
  "availableBalance": 2845
}

500 Server error (flat error shape)

{
  "error": "Failed to get balance"
}

Server error — safe to retry with backoff.

Get the full payout transaction history for an affiliate.

Response

200 Success

{
  "history": [
    {
      "id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
      "affiliateId": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
      "amount": 1200,
      "status": "paid",
      "requestDate": "2026-01-05",
      "paidDate": "2026-01-10",
      "createdAt": "2026-01-05T10:00:00Z",
      "updatedAt": "2026-01-10T14:00:00Z"
    },
    {
      "id": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
      "affiliateId": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
      "amount": 500,
      "status": "pending",
      "requestDate": "2026-03-15",
      "paidDate": null,
      "createdAt": "2026-03-15T09:30:00Z",
      "updatedAt": "2026-03-15T09:30:00Z"
    }
  ]
}

Payout Status Values

500 Server error (flat error shape)

{
  "error": "Failed to get payout history"
}

Server error — safe to retry with backoff.

Submit a payout request. The amount is validated against the affiliate's available balance.

Request Body

{
  "amount": 500
}

Response

201 Created

{
  "id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
  "affiliateId": "3f8a92b1-4e5c-4d2a-9f1b-8c7d6e5f4a3b",
  "amount": 500,
  "status": "pending",
  "requestDate": "2026-03-31",
  "paidDate": null,
  "createdAt": "2026-03-31T12:00:00Z",
  "updatedAt": "2026-03-31T12:00:00Z"
}

400 Validation error (flat error shape)

{
  "error": "Amount exceeds available balance"
}

500 Server error (flat error shape)

{
  "error": "Failed to create payout request"
}

Server error — safe to retry with backoff.

Get the affiliate's configured bank account. Returns the same shape that appears under affiliate.bankAccount in the login response, without the wrapper.

Response

200 Success

{
  "holderName": "Demo Affiliate ehf.",
  "bankName": "Landsbankinn",
  "iban": "IS140159260076545510730339",
  "swift": "NBIIISRE"
}

The swift field is null when no SWIFT/BIC code has been recorded.

404 Bank account not configured (nested error shape)

{
  "error": {
    "message": "Bank account not configured"
  }
}

404 Affiliate not found (nested error shape)

{
  "error": {
    "message": "Affiliate not found"
  }
}

500 Server error (nested error shape)

{
  "error": {
    "message": "Failed to get bank account"
  }
}

Server error — safe to retry with backoff.

Create or replace the affiliate's bank-account details. The IBAN is persisted in canonical form (uppercased, internal spaces stripped).

Request Body

{
  "holderName": "Demo Affiliate ehf.",
  "bankName": "Landsbankinn",
  "iban": "IS14 0159 2600 7654 5510 7303 39",
  "swift": "NBIIISRE"
}

Parameters

Accepted IBAN Formats

The iban field accepts any of the following (whitespace and case are normalised before matching):

Response

200 Success — returns the saved bank account in canonical form.

{
  "holderName": "Demo Affiliate ehf.",
  "bankName": "Landsbankinn",
  "iban": "IS140159260076545510730339",
  "swift": "NBIIISRE"
}

400 Validation error (nested error shape)

The message identifies the offending field. Possible values:

{
  "error": {
    "message": "invalid IBAN format"
  }
}

404 Affiliate not found (nested error shape)

{
  "error": {
    "message": "Affiliate not found"
  }
}

500 Server error (nested error shape)

{
  "error": {
    "message": "Failed to update bank account"
  }
}

Server error — safe to retry with backoff.

Get the affiliate's most recent notifications, ordered by creation time descending. Returns up to 100 records.

Response

200 Success — always an array, never null.

[
  {
    "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "title": "Payout approved",
    "body": "Your payout request of 500 ISK has been approved.",
    "createdAt": "2026-04-30T12:00:00Z",
    "read": false
  }
]

The read field is a real boolean — it becomes true once the notification's read_at timestamp is stamped. createdAt is RFC3339 UTC.

400 Invalid affiliate ID format (nested error shape)

{
  "error": {
    "message": "invalid affiliate ID format"
  }
}

404 Affiliate not found (nested error shape)

500 Server error (nested error shape)

{
  "error": {
    "message": "Failed to list notifications"
  }
}

Server error — safe to retry with backoff.

Stamp read_at on every unread notification for the affiliate. No request body required.

Response

200 Success — returns the count of rows updated.

{
  "updated": 3
}

updated is a non-negative integer (int64).

400 Invalid affiliate ID format (nested error shape)

{
  "error": {
    "message": "invalid affiliate ID format"
  }
}

404 Affiliate not found (nested error shape)

500 Server error (nested error shape)

{
  "error": {
    "message": "Failed to mark notifications read"
  }
}

Server error — safe to retry with backoff.

Stamp read_at on a single notification. No request body required.

Path Parameters

Response

200 Success

{
  "status": "ok"
}

400 Validation error (nested error shape)

The message identifies the offending field. Possible values:

{
  "error": {
    "message": "invalid notification ID format"
  }
}

404 Notification not found (nested error shape)

{
  "error": {
    "message": "Notification not found"
  }
}

500 Server error (nested error shape)

{
  "error": {
    "message": "Failed to mark notification read"
  }
}

Server error — safe to retry with backoff.