openapi: 3.0.3
info:
  title: Everflow Network API - Custom Caps
  description: >
    Endpoints for managing custom cap settings in the Everflow network.
    Custom caps let you set conversion, click, or impression limits at the
    partner or offer level — if both an offer and a partner have caps,
    Everflow stops conversions once either limit is reached. For setup,
    see the [Caps Management guide](https://helpdesk.everflow.io/customer/how-to-manage-caps).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Custom Caps
paths:
  /networks/custom/caps:
    get:
      summary: List Custom Caps
      tags:
        - Custom Caps
      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.
        - in: query
          name: "filter[network_offer_id]"
          schema:
            type: integer
          description: Filter by offer ID.
        - in: query
          name: "filter[network_affiliate_id]"
          schema:
            type: integer
          description: Filter by affiliate ID.
        - in: query
          name: "filter[time_created]"
          schema:
            type: string
          description: Filter by creation time.
        - in: query
          name: "filter[time_saved]"
          schema:
            type: string
          description: Filter by last update time.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_cap_settings:
                    type: array
                    items:
                      $ref: "#/components/schemas/CustomCap"
                  paging:
                    $ref: "#/components/schemas/Paging"
      security:
        - API Key: []
    post:
      summary: Create Custom Cap
      tags:
        - Custom Caps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomCapInput"
            example:
              network_affiliate_id: 28
              network_offer_id: 33
              is_soft_cap: false
              monthly_click_cap: 23
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomCap"
      security:
        - API Key: []
    patch:
      summary: Bulk Update Custom Caps
      tags:
        - Custom Caps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkUpdateRequest"
            example:
              network_custom_cap_setting_ids:
                - 1
                - 2
                - 3
              fields:
                - field_type: "daily_conversion_cap"
                  field_value: 150
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
      security:
        - API Key: []
  /networks/custom/capstable:
    post:
      summary: Find Custom Caps (Advanced)
      tags:
        - Custom Caps
      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.
        - in: query
          name: relationship
          schema:
            type: string
            enum:
              - affiliate
              - offer
              - all
          description: >
            Include related data. Use `affiliate` for affiliate details,
            `offer` for offer details, or `all` for both. Repeat the
            parameter for multiple values.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                search_terms:
                  type: array
                  description: Text search filters.
                  items:
                    type: object
                    properties:
                      search_type:
                        type: string
                        enum:
                          - offer
                          - affiliate
                        description: The field to search on.
                      value:
                        type: string
                        description: The search value.
                filters:
                  type: object
                  description: Structured filters to narrow results.
                  properties:
                    network_offer_ids:
                      type: array
                      items:
                        type: integer
                      description: Filter by offer IDs.
                    network_affiliate_ids:
                      type: array
                      items:
                        type: integer
                      description: Filter by affiliate IDs.
            example:
              search_terms: []
              filters: {}
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_cap_settings:
                    type: array
                    items:
                      $ref: "#/components/schemas/CustomCap"
                  paging:
                    $ref: "#/components/schemas/Paging"
      security:
        - API Key: []
  /networks/custom/caps/{settingId}:
    get:
      summary: Get Custom Cap by ID
      description: >
        Retrieve a single custom cap setting by its ID.
      tags:
        - Custom Caps
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom cap setting identifier.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomCap"
      security:
        - API Key: []
    delete:
      summary: Delete Custom Cap
      tags:
        - Custom Caps
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom cap setting identifier.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
      security:
        - API Key: []
components:
  schemas:
    CustomCap:
      type: object
      properties:
        network_custom_cap_setting_id:
          type: integer
          example: 1
          description: Unique custom cap setting ID.
        network_id:
          type: integer
          example: 1
          description: Network ID.
        network_affiliate_id:
          type: integer
          example: 28
          description: The affiliate ID.
        network_offer_id:
          type: integer
          example: 33
          description: The offer ID.
        name:
          type: string
          description: The custom cap setting name.
        daily_conversion_cap:
          type: integer
          description: The daily conversion cap (0 for unlimited).
        weekly_conversion_cap:
          type: integer
          description: The weekly conversion cap (0 for unlimited).
        monthly_conversion_cap:
          type: integer
          description: The monthly conversion cap (0 for unlimited).
        global_conversion_cap:
          type: integer
          description: The global conversion cap (0 for unlimited).
        daily_payout_cap:
          type: number
          format: double
          description: The daily payout cap (0 for unlimited).
        weekly_payout_cap:
          type: number
          format: double
          description: The weekly payout cap (0 for unlimited).
        monthly_payout_cap:
          type: number
          format: double
          description: The monthly payout cap (0 for unlimited).
        global_payout_cap:
          type: number
          format: double
          description: The global payout cap (0 for unlimited).
        daily_click_cap:
          type: integer
          description: The daily click cap (0 for unlimited).
        weekly_click_cap:
          type: integer
          description: The weekly click cap (0 for unlimited).
        monthly_click_cap:
          type: integer
          description: The monthly click cap (0 for unlimited).
        global_click_cap:
          type: integer
          description: The global click cap (0 for unlimited).
        daily_revenue_cap:
          type: number
          format: double
          description: The daily revenue cap (0 for unlimited).
        weekly_revenue_cap:
          type: number
          format: double
          description: The weekly revenue cap (0 for unlimited).
        monthly_revenue_cap:
          type: number
          format: double
          description: The monthly revenue cap (0 for unlimited).
        global_revenue_cap:
          type: number
          format: double
          description: The global revenue cap (0 for unlimited).
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        is_soft_cap:
          type: boolean
          description: Whether this is a soft cap (allows conversions beyond the cap limit).
        relationship:
          type: object
          properties:
            affiliate:
              type: object
              description: Associated affiliate details.
              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: Account status of the affiliate.
            offer:
              type: object
              description: Associated offer details.
              properties:
                network_offer_id:
                  type: integer
                  description: Unique offer ID.
                network_id:
                  type: integer
                  description: Network ID.
                network_advertiser_id:
                  type: integer
                  description: Advertiser ID that owns this offer.
                network_offer_group_id:
                  type: integer
                  description: Offer group ID (0 if not grouped).
                name:
                  type: string
                  description: Offer name.
                offer_status:
                  type: string
                  description: Status of the offer.
                network_tracking_domain_id:
                  type: integer
                  description: Tracking domain ID for this offer.
                visibility:
                  type: string
                  description: Visibility setting for this offer.
                currency_id:
                  type: string
                  description: Currency code for this offer.
    CustomCapInput:
      type: object
      required:
        - network_affiliate_id
        - network_offer_id
      properties:
        network_affiliate_id:
          type: integer
          description: The affiliate ID.
        network_offer_id:
          type: integer
          description: The offer ID.
        name:
          type: string
          description: The custom cap setting name.
        daily_conversion_cap:
          type: integer
          description: The daily conversion cap (0 for unlimited).
        weekly_conversion_cap:
          type: integer
          description: The weekly conversion cap (0 for unlimited).
        monthly_conversion_cap:
          type: integer
          description: The monthly conversion cap (0 for unlimited).
        global_conversion_cap:
          type: integer
          description: The global conversion cap (0 for unlimited).
        daily_payout_cap:
          type: number
          format: double
          description: The daily payout cap (0 for unlimited).
        weekly_payout_cap:
          type: number
          format: double
          description: The weekly payout cap (0 for unlimited).
        monthly_payout_cap:
          type: number
          format: double
          description: The monthly payout cap (0 for unlimited).
        global_payout_cap:
          type: number
          format: double
          description: The global payout cap (0 for unlimited).
        daily_click_cap:
          type: integer
          description: The daily click cap (0 for unlimited).
        weekly_click_cap:
          type: integer
          description: The weekly click cap (0 for unlimited).
        monthly_click_cap:
          type: integer
          description: The monthly click cap (0 for unlimited).
        global_click_cap:
          type: integer
          description: The global click cap (0 for unlimited).
        daily_revenue_cap:
          type: number
          format: double
          description: The daily revenue cap (0 for unlimited).
        weekly_revenue_cap:
          type: number
          format: double
          description: The weekly revenue cap (0 for unlimited).
        monthly_revenue_cap:
          type: number
          format: double
          description: The monthly revenue cap (0 for unlimited).
        global_revenue_cap:
          type: number
          format: double
          description: The global revenue cap (0 for unlimited).
        is_soft_cap:
          type: boolean
          description: >
            Whether this is a soft cap. Hard caps (false) stop conversions once
            the limit is reached. Soft caps (true) allow conversions beyond the
            limit.
    BulkUpdateRequest:
      type: object
      required:
        - network_custom_cap_setting_ids
        - fields
      properties:
        network_custom_cap_setting_ids:
          type: array
          items:
            type: integer
          description: List of custom cap setting IDs to update.
        fields:
          type: array
          items:
            type: object
            properties:
              field_type:
                type: string
                enum:
                  - daily_conversion_cap
                  - weekly_conversion_cap
                  - monthly_conversion_cap
                  - global_conversion_cap
                  - daily_payout_cap
                  - weekly_payout_cap
                  - monthly_payout_cap
                  - global_payout_cap
                  - daily_click_cap
                  - weekly_click_cap
                  - monthly_click_cap
                  - global_click_cap
                  - daily_revenue_cap
                  - weekly_revenue_cap
                  - monthly_revenue_cap
                  - global_revenue_cap
                description: The cap field to update.
              field_value:
                description: The new cap value.
    Paging:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total_count:
          type: integer
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey