Affitor Tracking API

openapi: 3.2.0
info:
  title: Affitor Tracking API
  version: 1.0.0
  description: 'Server-to-server tracking API for Affitor advertisers.


    The integration is a three-step funnel:

    1. **Click** — captured automatically by the Affitor tracker script (`?aff=` links), or reported server-side.

    2. **Lead** — ties your internal customer ID (`customer_key`) to the click at signup.

    3. **Sale** — reports revenue; Affitor resolves the partner and computes commission.


    Refunds and chargebacks are reported via the Refund endpoint (or handled

    automatically when using Stripe webhook tracking).


    ## Authentication

    Server-to-server calls use your **program API key** as a Bearer token:

    `Authorization: Bearer `.

    Find it in your advertiser dashboard under Program Settings (shown masked;

    regenerating issues a new key and invalidates the old one immediately).


    ## Test mode

    The click, lead and sale endpoints accept `additional_data: { "test_mode": true }`

    to create isolated test events (`is_test: true`) that never touch production

    attribution or commissions and are left out of revenue analytics; they can

    move your setup checklist. `POST /api/v1/track/refund` has no test mode:

    with your program API key it is processed as a real refund.

    Full guide: https://affitor.com/docs/api-reference/test-mode


    ## Attribution rules

    - Model: first click wins inside a program. When a later click from

    another partner sends the stored `click_id` as `existing_click_id` (the

    tracker does), that click is recorded for the new partner, but the

    customer, its `click_id` and its partner do not change.

    - Attribution window: program-level `attribution_window_days` (default 60).

    Sales for customers whose first-click anchor is outside the window return

    `attributed: false` and create nothing.

    - Customer lifecycle: `click → lead → conversion` (status never regresses).'
  contact:
    name: Affitor Support
    url: https://affitor.com/docs/support/contact
servers:
- url: https://api.affitor.com
  description: Production
security: []
tags:
- name: Tracking
  description: Click, lead, sale, and refund tracking
paths:
  /api/v1/track/click:
    post:
      operationId: trackClick
      tags:
      - Tracking
      summary: Track a click
      description: 'Records an affiliate click. Normally called by the Affitor tracker

        script when a visitor lands with `?aff=`; can also be

        called server-side. No authentication required — attribution is proven

        by the `aff` short code inside `affiliate_url`.


        On success, store the returned `click_id` in a first-party cookie named

        `affitor_click_id` with a lifetime of `cookie_window_days` days.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClickRequest'
            examples:
              production:
                summary: Real click
                value:
                  affiliate_url: https://yoursite.com/pricing?aff=abc123
                  page_url: https://yoursite.com/pricing?aff=abc123
                  page_title: Pricing
                  referrer_url: https://google.com
                  session_id: sess_xyz_1234
              test_mode:
                summary: Test mode
                value:
                  additional_data:
                    test_mode: true
                    program_id: YOUR_PROGRAM_ID
      responses:
        '200':
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          description: Click recorded.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ClickResponse'
                - $ref: '#/components/schemas/TestModeResponse'
              examples:
                recorded:
                  value:
                    success: true
                    click_id: cust_42_1714000000000
                    partner_code: abc123
                    cookie_window_days: 60
components:
  headers:
    RateLimit:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    RateLimitPolicy:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    XRateLimitRemaining:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    XRateLimitLimit:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    XRateLimitReset:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  schemas:
    TestModeResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ClickResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ClickRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true