openapi: 3.0.3
info:
  title: Everflow Network API - Affiliates (Additional Endpoints)
  description: Additional affiliate management endpoints for the Everflow network.
  version: 1.0.0
servers:
  - description: Production Server
    url: https://api.eflow.team/v1
tags:
  - name: Affiliates
    description: Additional affiliate management endpoints.
paths:
  /networks/patch/affiliates/apply:
    patch:
      summary: Apply Affiliate Bulk Edit
      tags:
        - Affiliates
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_affiliate_ids: [7]
              fields:
                - field_type: "account_status"
                  field_value: "active"
                  operator: "overwrite"
            schema:
              $ref: "#/components/schemas/AffiliatePatchInput"
      responses:
        "200":
          description: Changes applied successfully.
          content:
            application/json:
              example:
                result: true
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the bulk edit was applied successfully.
      security:
        - API Key: []

  /networks/patch/affiliates/submit:
    post:
      summary: Affiliate Bulk Edit Preview
      tags:
        - Affiliates
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_affiliate_ids: [7]
              fields:
                - field_type: "account_status"
                  field_value: "inactive"
                  operator: "overwrite"
            schema:
              $ref: "#/components/schemas/AffiliatePatchInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                changes:
                  - network_affiliate:
                      network_affiliate_id: 7
                      network_id: 1
                      name: "Frances Holder Inc."
                      account_status: "active"
                    change_status: "ok"
                    current_field:
                      field_type: "account_status"
                      field_value: "active"
                      operator: "overwrite"
                    changed_field:
                      field_type: "account_status"
                      field_value: "inactive"
                      operator: "overwrite"
                    error_message: ""
                    related_changes: ""
                resource_errors: []
              schema:
                $ref: "#/components/schemas/AffiliatePatchResponse"
      security:
        - API Key: []

  /networks/offers/{offerId}/affiliateids/runnable:
    get:
      summary: Get Runnable Affiliate IDs for Offer
      tags:
        - Affiliates
      parameters:
        - in: path
          name: offerId
          required: true
          schema:
            type: integer
          description: The offer ID.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer_ids:
                    type: array
                    items:
                      type: integer
                      description: "An offer ID."
                    description: Array of offer IDs the affiliate can run.
      security:
        - API Key: []

  /networks/affiliates/{affiliateId}/trackingurls:
    post:
      summary: Get Affiliate Tracking URLs
      tags:
        - Affiliates
      parameters:
        - in: path
          name: affiliateId
          required: true
          schema:
            type: integer
          description: The affiliate ID.
      requestBody:
        required: true
        content:
          application/json:
            example:
              is_all_offers: true
              network_offer_ids: []
            schema:
              type: object
              required:
                - is_all_offers
              properties:
                is_all_offers:
                  type: boolean
                  description: >
                    When true, tracking URLs for all offers the affiliate has
                    access to will be returned. When false, you must supply
                    specific offer IDs in the `network_offer_ids` array.
                network_offer_ids:
                  type: array
                  items:
                    type: integer
                    description: "An offer ID."
                  description: >
                    Array of offer IDs to retrieve tracking URLs for. Required
                    when `is_all_offers` is false.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  tracking_urls:
                    type: array
                    description: List of tracking URL records.
                    items:
                      type: object
                      description: Tracking URL record.
      security:
        - API Key: []

  /networks/affiliates/{affiliateId}/referral:
    post:
      summary: Create Affiliate Referral
      tags:
        - Affiliates
      parameters:
        - in: path
          name: affiliateId
          required: true
          schema:
            type: integer
          description: The affiliate ID being referred.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                referring_affiliate_id:
                  type: integer
                  description: The ID of the affiliate who made the referral.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the referral was created successfully.
      security:
        - API Key: []

components:
  schemas:
    AffiliatePatchInput:
      description: "Input for bulk editing affiliates."
      type: object
      required:
        - network_affiliate_ids
        - fields
      properties:
        network_affiliate_ids:
          type: array
          description: IDs of the affiliates to be patched.
          items:
            type: integer
            description: "An affiliate ID to patch."
        fields:
          type: array
          description: List of fields to patch.
          items:
            type: object
            description: "A field patch operation."
            required:
              - field_type
              - field_value
              - operator
            properties:
              field_type:
                type: string
                description: >
                  Type of the field to patch. See Patchable Fields below for the
                  full list of supported field types.
                enum:
                  - network_employee_id
                  - account_executive_id
                  - referrer_id
                  - labels
                  - affiliate_name
                  - account_status
                  - default_currency_id
                  - has_notifications
                  - enable_media_cost_tracking_links
                  - network_traffic_source_id
                  - internal_notes
                  - billing_payment_method
                  - billing_billing_frequency
                  - billing_weekly
                  - billing_bimonthly
                  - billing_monthly
                  - billing_two_months
                  - billing_quarterly
                  - billing_is_invoice_creation_auto
                  - billing_invoice_amount_threshold
                  - billing_auto_invoice_start_date
                  - billing_invoice_generation_days_delay
                  - billing_default_payment_terms
                  - billing_default_invoice_is_hidden
                  - referral_is_enabled
                  - referral_method
                  - referral_value
                  - referral_commission_basis
                  - referral_minimum_threshold
                  - referral_duration
              field_value:
                description: >
                  Value of the field to patch. The type depends on the `field_type`:

                  - **network_employee_id** (int) — The employee ID of the affiliate's account manager.

                  - **account_executive_id** (int) — The employee ID of the affiliate's account executive.

                  - **referrer_id** (int) — The affiliate ID of the account that referred the target affiliate(s).

                  - **labels** (string array) — The list of labels associated with the affiliate.

                  - **affiliate_name** (string) — The name of the affiliate.

                  - **account_status** (string) — Status of the affiliate. Values: `active`, `inactive`, `suspended`.

                  - **default_currency_id** (string) — The affiliate's default currency from the metadata API. Can be overwritten at the affiliate user level.

                  - **has_notifications** (boolean) — Whether the affiliate can receive notifications.

                  - **enable_media_cost_tracking_links** (boolean) — Whether the cost parameter will be processed or ignored on clicks.

                  - **network_traffic_source_id** (int) — An optional tracking source ID for the affiliate.

                  - **internal_notes** (string) — Internal notes not visible to the affiliate.

                  - **billing_payment_method** (string) — Only `pay` is supported (requires Everflow Pay integration).

                  - **billing_billing_frequency** (string) — Values: `weekly`, `bimonthly`, `monthly`, `two_months`, `quarterly`, `manual`, `other`. When setting this, you must also set the corresponding frequency details (e.g. `billing_weekly`).

                  - **billing_weekly** (string) — Day of week. Values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Required when frequency is `weekly`.

                  - **billing_bimonthly** (object) — `{ "day_of_month_one": int, "day_of_month_two": int }`. Required when frequency is `bimonthly`.

                  - **billing_monthly** (object) — `{ "day_of_month": int }`. Required when frequency is `monthly`.

                  - **billing_two_months** (object) — `{ "starting_month": int, "day_of_month": int }`. Required when frequency is `two_months`.

                  - **billing_quarterly** (object) — `{ "starting_month": int, "day_of_month": int }`. Required when frequency is `quarterly`.

                  - **billing_is_invoice_creation_auto** (boolean) — Whether invoices are generated automatically.

                  - **billing_invoice_amount_threshold** (double) — Minimum amount before an invoice is generated.

                  - **billing_auto_invoice_start_date** (date) — Lookback window start date. Required when auto invoicing is enabled.

                  - **billing_invoice_generation_days_delay** (int) — Days after billing period before invoice is generated.

                  - **billing_default_payment_terms** (int) — Number of days before payment is sent.

                  - **billing_default_invoice_is_hidden** (boolean) — Whether invoices are hidden from affiliates by default.

                  - **referral_is_enabled** (boolean) — Whether referral commissions are enabled.

                  - **referral_method** (string) — Values: `flat_fee`, `percentage`.

                  - **referral_value** (double) — Value of the referral commission.

                  - **referral_commission_basis** (string) — Values: `payout`, `revenue`, `profit`.

                  - **referral_minimum_threshold** (double) — Minimum amount before a commission is paid.

                  - **referral_duration** (double) — Number of days during which the referral commission is effective.
              operator:
                type: string
                description: >
                  Operator determining how the field will be used to modify the
                  affiliates.
                enum:
                  - overwrite
                  - append
                  - delete
                  - clear
    AffiliatePatchResponse:
      description: "Response from bulk edit preview or apply."
      type: object
      properties:
        changes:
          type: array
          description: Proposed changes for each affiliate.
          items:
            type: object
            description: "A change record for a single affiliate."
            properties:
              network_affiliate:
                type: object
                description: The affiliate being changed.
                properties:
                  network_affiliate_id:
                    type: integer
                    description: Unique affiliate ID.
                  network_id:
                    type: integer
                    description: Network ID.
                  name:
                    type: string
                    description: Affiliate name.
                  account_status:
                    type: string
                    description: Current account status.
              change_status:
                type: string
                description: Status of the change (e.g. "ok", "error").
              current_field:
                type: object
                description: Current value of the field.
                properties:
                  field_type:
                    type: string
                    description: The field type being changed.
                  field_value:
                    description: The current value of the field.
                  operator:
                    type: string
                    description: The operator used.
              changed_field:
                type: object
                description: Proposed new value.
                properties:
                  field_type:
                    type: string
                    description: The field type being changed.
                  field_value:
                    description: The proposed new value.
                  operator:
                    type: string
                    description: The operator used.
              error_message:
                type: string
                description: Error message if the change would fail.
              related_changes:
                type: string
                description: Description of any side-effect changes.
        resource_errors:
          type: array
          description: Errors for affiliates that could not be processed.
          items:
            type: object
            description: "An error record for an affiliate that could not be processed."
            properties:
              id:
                type: integer
                description: Affiliate ID that errored.
              label:
                type: string
                description: Affiliate name.
              message:
                type: string
                description: Error description.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey