openapi: 3.0.3
info:
  title: Everflow Network API - Tiered Commissions
  description: >
    Endpoints for managing tiered commission structures. Tiered commissions
    automatically adjust partner payouts or revenue based on performance
    metrics like conversion count, sales volume, or revenue thresholds
    within specified time periods. For setup, see the [Tiered Commissions
    guide](https://helpdesk.everflow.io/customer/tiered-commissions).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Tiered Commissions
paths:
  /networks/tieredcommissions/table:
    post:
      summary: Find Tiered Commissions (Advanced)
      tags:
        - Tiered Commissions
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number (1-based).
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
          description: Number of results per page.
      requestBody:
        content:
          application/json:
            example:
              search_terms:
                - search_type: "name"
                  value: "Silver"
              filters:
                network_affiliate_ids: [21]
                network_offer_ids: [4, 6]
                network_advertiser_ids: []
            schema:
              type: object
              properties:
                search_terms:
                  type: array
                  description: Text search filters.
                  items:
                    type: object
                    required:
                      - search_type
                      - value
                    properties:
                      search_type:
                        type: string
                        description: The name of the field used for search. Only "name" is supported.
                        example: "name"
                      value:
                        type: string
                        description: The value to search.
                        example: "Silver"
                filters:
                  type: object
                  description: Structured filters to narrow results.
                  properties:
                    network_affiliate_ids:
                      type: array
                      items:
                        type: integer
                      description: ID of the Affiliates.
                    network_offer_ids:
                      type: array
                      items:
                        type: integer
                      description: ID of the offers.
                    network_advertiser_ids:
                      type: array
                      items:
                        type: integer
                      description: ID of the advertisers.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  commissions:
                    type: array
                    items:
                      $ref: "#/components/schemas/TieredCommissionTableItem"
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []
  /networks/tieredcommissions/{commissionId}:
    get:
      summary: Get Tiered Commission
      description: >
        Retrieve a single tiered commission configuration by its ID.
      tags:
        - Tiered Commissions
      parameters:
        - in: path
          name: commissionId
          required: true
          schema:
            type: integer
          description: The ID of the tiered commission you want to fetch.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TieredCommission"
        "404":
          description: Tiered commission not found.
      security:
        - API Key: []
    put:
      summary: Update Tiered Commission
      tags:
        - Tiered Commissions
      parameters:
        - in: path
          name: commissionId
          required: true
          schema:
            type: integer
          description: The ID of the tiered commission you want to update.
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: "SilverCommission"
              notes: "Monthly payement"
              status: "active"
              start_date: "2020-07-23"
              end_date: "2020-08-22"
              period: "monthly"
              network_offer_payout_revenue_id: 0
              is_apply_all_affiliates: false
              network_affiliate_ids: [21, 35, 28]
              network_offer_ids: [1, 15, 12]
              network_advertiser_ids: null
              is_payout_enabled: true
              payout_action: "increase"
              payout_value: 10
              is_revenue_enabled: true
              revenue_action: "decrease"
              revenue_value: 6
              payout_goal: 0
              revenue_goal: 121
              sale_amount_goal: 0
              conversion_goal: 10
              event_goal: 0
              relationship: {}
              payout_max: 0
              revenue_max: 1000
              sale_amount_max: 0
              conversion_max: 0
              event_max: 0
              is_retroactive_payout_enabled: true
              retroactive_payout_action: "flat_increase"
              retroactive_payout_value: 5
              is_retroactive_revenue_enabled: false
              retroactive_revenue_action: ""
              retroactive_revenue_value: 0
            schema:
              $ref: "#/components/schemas/TieredCommissionInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TieredCommission"
        "404":
          description: Tiered commission not found.
      security:
        - API Key: []
  /networks/tieredcommissions:
    post:
      summary: Create Tiered Commission
      tags:
        - Tiered Commissions
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: "SilverCommission"
              notes: "Monthly payement"
              status: "active"
              start_date: "2020-07-23"
              end_date: "2020-08-22"
              period: "monthly"
              network_offer_payout_revenue_id: 0
              is_apply_all_affiliates: false
              network_affiliate_ids: [21, 35, 28]
              network_offer_ids: [1, 15, 12]
              network_advertiser_ids: null
              is_payout_enabled: true
              payout_action: "increase"
              payout_value: 10
              is_revenue_enabled: true
              revenue_action: "decrease"
              revenue_value: 6
              payout_goal: 0
              revenue_goal: 121
              sale_amount_goal: 0
              conversion_goal: 10
              event_goal: 0
              relationship: {}
              payout_max: 0
              revenue_max: 1000
              sale_amount_max: 0
              conversion_max: 0
              event_max: 0
              is_retroactive_payout_enabled: true
              retroactive_payout_action: "flat_increase"
              retroactive_payout_value: 5
              is_retroactive_revenue_enabled: false
              retroactive_revenue_action: ""
              retroactive_revenue_value: 0
            schema:
              $ref: "#/components/schemas/TieredCommissionInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TieredCommission"
      security:
        - API Key: []
components:
  schemas:
    TieredCommission:
      type: object
      description: A tiered commission configuration with all computed and relational fields.
      properties:
        network_tiered_commission_id:
          type: integer
          description: Unique tiered commission ID.
          example: 1
        network_id:
          type: integer
          description: Network ID.
          example: 1
        name:
          type: string
          description: The name of the tiered commission.
          example: "SilverCommission"
        notes:
          type: string
          description: Note for internal usage.
          example: "Monthly payement"
        status:
          type: string
          description: The tiered commissions status. Can either be `active` or `inactive`.
          enum:
            - active
            - inactive
          example: "active"
        start_date:
          type: string
          description: Start of when rule goes into effect. This can be set to a future date.
          example: "2020-07-23"
        end_date:
          type: string
          description: End of when rule goes into effect.
          example: "2020-08-22"
        period:
          type: string
          description: The tiered commissions period. Can either be `daily`, `weekly`, `monthly`, `quarterly` or `global`.
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
            - global
          example: "monthly"
        network_offer_payout_revenue_id:
          type: integer
          description: ID of the offer payout revenue.
          example: 0
        is_apply_all_affiliates:
          type: boolean
          description: Whether or not you want to apply the tiered commission to all affiliates. Defaults to false.
          example: false
        network_affiliate_ids:
          type: array
          items:
            type: integer
          description: ID of the Affiliates.
          example: [21, 35, 28]
        network_offer_ids:
          type: array
          items:
            type: integer
          description: ID of the offers.
          example: [1, 15, 12]
        network_advertiser_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: ID of the advertisers.
          example: null
        is_payout_enabled:
          type: boolean
          description: Whether or not you want to enable the payout settings. Defaults to false.
          example: true
        payout_action:
          type: string
          description: >
            Type of payout action. Note: sending `exact` will be stored as `unknown` — use only
            `increase`, `decrease`, `flat_increase`, or `flat_decrease`.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - unknown
          example: "increase"
        payout_value:
          type: number
          description: The payout modifier value. Required only if `is_payout_enabled` is true. Must be greater than 0.
          example: 10
        is_revenue_enabled:
          type: boolean
          description: Whether or not you want to enable the revenue. Defaults to false.
          example: true
        revenue_action:
          type: string
          description: >
            Type of revenue action. Note: sending `exact` will be stored as `unknown` — use only
            `increase`, `decrease`, `flat_increase`, or `flat_decrease`.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - unknown
          example: "decrease"
        revenue_value:
          type: number
          description: The revenue modifier value. Required only if `is_revenue_enabled` is true. Must be greater than 0.
          example: 6
        payout_goal:
          type: integer
          description: The payout goal of your tiered commission.
          example: 0
        revenue_goal:
          type: integer
          description: The revenue goal of your tiered commission.
          example: 121
        sale_amount_goal:
          type: integer
          description: The sale amount goal of your tiered commission.
          example: 0
        conversion_goal:
          type: integer
          description: The conversion goal of your tiered commission.
          example: 10
        event_goal:
          type: integer
          description: The event goal of your tiered commission.
          example: 0
        relationship:
          type: object
          description: Related entities. Always returns an empty object `{}` in practice.
        payout_max:
          type: integer
          description: The maximum percentage of payout allowed.
          example: 0
        revenue_max:
          type: integer
          description: The maximum amount of revenue allowed.
          example: 1000
        sale_amount_max:
          type: integer
          description: The maximum number of sale amount allowed.
          example: 0
        conversion_max:
          type: integer
          description: The maximum number of conversions allowed.
          example: 0
        event_max:
          type: integer
          description: The maximum number of events allowed.
          example: 0
        is_retroactive_payout_enabled:
          type: boolean
          description: Whether retroactive payout adjustments are enabled.
          example: false
        retroactive_payout_action:
          type: string
          description: >
            The retroactive payout action type. Retroactive actions support `exact`
            in addition to the standard action types.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - exact
            - unknown
          example: "flat_increase"
        retroactive_payout_value:
          type: number
          description: The retroactive payout modifier value.
          example: 0
        retroactive_payout_type:
          type: string
          description: The retroactive payout type.
          enum:
            - blank
            - cpc
            - cpa
            - cpm
            - cps
            - cpa_cps
            - prv
            - cpa_sku
            - cps_sku
            - cpa_cps_sku
            - prv_sku
          example: "blank"
        retroactive_payout_percentage:
          type: number
          description: The retroactive payout percentage.
          example: 0
        is_retroactive_revenue_enabled:
          type: boolean
          description: Whether retroactive revenue adjustments are enabled.
          example: false
        retroactive_revenue_action:
          type: string
          description: >
            The retroactive revenue action type. Retroactive actions support `exact`
            in addition to the standard action types.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - exact
            - unknown
          example: "flat_decrease"
        retroactive_revenue_value:
          type: number
          description: The retroactive revenue modifier value.
          example: 0
        retroactive_revenue_type:
          type: string
          description: The retroactive revenue type.
          enum:
            - blank
            - rpc
            - rpa
            - rpm
            - rps
            - rpa_rps
            - rpa_sku
            - rps_sku
            - rpa_rps_sku
          example: "blank"
        retroactive_revenue_percentage:
          type: number
          description: The retroactive revenue percentage.
          example: 0
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
    TieredCommissionTableItem:
      type: object
      description: >
        A tiered commission as returned by the table/list endpoint. This is a
        subset of the full TieredCommission schema — it omits retroactive fields,
        network_affiliate_ids, network_offer_ids, and network_advertiser_ids.
      properties:
        network_tiered_commission_id:
          type: integer
          description: Unique tiered commission ID.
        network_id:
          type: integer
          description: Network ID.
        name:
          type: string
          description: The name of the tiered commission.
        notes:
          type: string
          description: Note for internal usage.
        status:
          type: string
          description: The tiered commissions status.
          enum:
            - active
            - inactive
        start_date:
          type: string
          description: Start of when rule goes into effect.
        end_date:
          type: string
          description: End of when rule goes into effect.
        period:
          type: string
          description: The tiered commissions period.
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
            - global
        network_offer_payout_revenue_id:
          type: integer
          description: ID of the offer payout revenue.
        is_apply_all_affiliates:
          type: boolean
          description: Whether the tiered commission applies to all affiliates.
        is_payout_enabled:
          type: boolean
          description: Whether payout settings are enabled.
        payout_action:
          type: string
          description: Type of payout action.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - unknown
        payout_value:
          type: number
          description: The payout modifier value.
        is_revenue_enabled:
          type: boolean
          description: Whether revenue settings are enabled.
        revenue_action:
          type: string
          description: Type of revenue action.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - unknown
        revenue_value:
          type: number
          description: The revenue modifier value.
        payout_goal:
          type: integer
          description: The payout goal.
        revenue_goal:
          type: integer
          description: The revenue goal.
        sale_amount_goal:
          type: integer
          description: The sale amount goal.
        conversion_goal:
          type: integer
          description: The conversion goal.
        event_goal:
          type: integer
          description: The event goal.
        relationship:
          type: object
          description: Related entities. Always returns an empty object `{}`.
        payout_max:
          type: integer
          description: The maximum payout allowed.
        revenue_max:
          type: integer
          description: The maximum revenue allowed.
        sale_amount_max:
          type: integer
          description: The maximum sale amount allowed.
        conversion_max:
          type: integer
          description: The maximum conversions allowed.
        event_max:
          type: integer
          description: The maximum events allowed.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
    TieredCommissionInput:
      type: object
      description: >
        Input schema for creating or updating a tiered commission. At least one
        goal field (conversion_goal, event_goal, sale_amount_goal, payout_goal,
        or revenue_goal) must be greater than 0. If payout or revenue is enabled,
        the corresponding action and value fields are required.
      required:
        - name
        - status
        - start_date
        - end_date
        - period
        - is_payout_enabled
        - payout_action
        - payout_value
        - is_revenue_enabled
        - revenue_action
        - revenue_value
        - network_offer_ids
      properties:
        name:
          type: string
          description: The name of the tiered commission.
          example: "SilverCommission"
        notes:
          type: string
          description: Note for internal usage.
          example: "Monthly payement"
        status:
          type: string
          description: The tiered commissions status. Can either be `active` or `inactive`.
          enum:
            - active
            - inactive
          example: "active"
        start_date:
          type: string
          description: Start of when rule goes into effect. This can be set to a future date.
          example: "2020-07-23"
        end_date:
          type: string
          description: End of when rule goes into effect.
          example: "2020-08-22"
        period:
          type: string
          description: The tiered commissions period. Can either be `daily`, `weekly`, `monthly`, `quarterly` or `global`.
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
            - global
          example: "monthly"
        network_offer_payout_revenue_id:
          type: integer
          description: ID of the offer payout revenue. Defaults to `0`.
          example: 0
        is_apply_all_affiliates:
          type: boolean
          description: Whether or not you want to apply the tiered commission to all affiliates. Defaults to `false`.
          example: false
        network_affiliate_ids:
          type: array
          items:
            type: integer
          description: ID of the Affiliates.
          example: [21, 35, 28]
        network_offer_ids:
          type: array
          items:
            type: integer
          description: ID of the offers.
          example: [1, 15, 12]
        network_advertiser_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: ID of the advertisers.
        is_payout_enabled:
          type: boolean
          description: Whether or not you want to enable the payout settings. Defaults to `false`.
          example: true
        payout_action:
          type: string
          description: >
            Type of payout action. Required only if `is_payout_enabled` is true.
            Do not use `exact` — it will be stored as `unknown`.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
          example: "increase"
        payout_value:
          type: number
          description: The payout modifier value. Required only if `is_payout_enabled` is true. Must be greater than 0.
          example: 10
        is_revenue_enabled:
          type: boolean
          description: Whether or not you want to enable the revenue. Defaults to `false`.
          example: true
        revenue_action:
          type: string
          description: >
            Type of revenue action. Required only if `is_revenue_enabled` is true.
            Do not use `exact` — it will be stored as `unknown`.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
          example: "decrease"
        revenue_value:
          type: number
          description: The revenue modifier value. Required only if `is_revenue_enabled` is true. Must be greater than 0.
          example: 6
        payout_goal:
          type: integer
          description: The payout goal of your tiered commission. Defaults to `0`.
          example: 0
        revenue_goal:
          type: integer
          description: The revenue goal of your tiered commission. Defaults to `0`.
          example: 121
        sale_amount_goal:
          type: integer
          description: The sale amount goal of your tiered commission. Defaults to `0`.
          example: 0
        conversion_goal:
          type: integer
          description: The conversion goal of your tiered commission. Defaults to `0`.
          example: 10
        event_goal:
          type: integer
          description: The event goal of your tiered commission. Defaults to `0`.
          example: 0
        relationship:
          type: object
          description: Related entities. Pass an empty object `{}`.
        payout_max:
          type: integer
          description: >
            The maximum payout allowed. If set, must be greater than
            `payout_goal`. Defaults to `0` (no maximum).
          example: 0
        revenue_max:
          type: integer
          description: >
            The maximum revenue allowed. If set, must be greater than
            `revenue_goal`. Defaults to `0` (no maximum).
          example: 1000
        sale_amount_max:
          type: integer
          description: >
            The maximum sale amount allowed. If set, must be greater than
            `sale_amount_goal`. Defaults to `0` (no maximum).
          example: 0
        conversion_max:
          type: integer
          description: >
            The maximum conversions allowed. If set, must be greater than
            `conversion_goal`. Defaults to `0` (no maximum).
          example: 0
        event_max:
          type: integer
          description: >
            The maximum events allowed. If set, must be greater than
            `event_goal`. Defaults to `0` (no maximum).
          example: 0
        is_retroactive_payout_enabled:
          type: boolean
          description: Whether retroactive payout adjustments are enabled. Defaults to `false`.
          example: false
        retroactive_payout_action:
          type: string
          description: >
            The retroactive payout action type. Required only if
            `is_retroactive_payout_enabled` is true. Supports `exact` unlike
            regular payout actions.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - exact
          example: "flat_increase"
        retroactive_payout_value:
          type: number
          description: >
            The retroactive payout modifier value. Required only if
            `is_retroactive_payout_enabled` is true. Must be greater than 0.
          example: 5
        is_retroactive_revenue_enabled:
          type: boolean
          description: Whether retroactive revenue adjustments are enabled. Defaults to `false`.
          example: false
        retroactive_revenue_action:
          type: string
          description: >
            The retroactive revenue action type. Required only if
            `is_retroactive_revenue_enabled` is true. Supports `exact` unlike
            regular revenue actions.
          enum:
            - increase
            - decrease
            - flat_increase
            - flat_decrease
            - exact
          example: "flat_decrease"
        retroactive_revenue_value:
          type: number
          description: >
            The retroactive revenue modifier value. Required only if
            `is_retroactive_revenue_enabled` is true. Must be greater than 0.
          example: 5
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey