openapi: 3.0.1
info:
  title: FirstPromoter Admin Commissions Promoter Campaigns API
  version: '2.0'
  description: REST API for managing affiliate programs, promoters, campaigns, referrals, rewards, and payouts in FirstPromoter. Supports pagination, filtering, and full CRUD operations across all affiliate program resources.
  contact:
    url: https://docs.firstpromoter.com
  license:
    name: Proprietary
    url: https://firstpromoter.com/terms
servers:
- url: https://api.firstpromoter.com/api/v2
  description: Production server
security:
- BearerAuth: []
tags:
- name: Promoter Campaigns
paths:
  /company/promoter_campaigns:
    get:
      summary: Get available promoter campaigns
      description: "With this endpoint you can list all promoter campaigns. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns`</Tip>"
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: List of promoter campaigns
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromoterCampaign'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/search:
    get:
      summary: 'Returns results for promoter campaigns dropdown search. Max results: 5'
      description: "With this endpoint you can search for promoter campaigns. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns/search?q=...`</Tip>"
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: query
        name: q
        required: true
        schema:
          type: string
        description: Search params
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromoterCampaign'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/{id}:
    put:
      summary: Update promoter campaign
      operationId: updatePromoterCampaign
      description: "With this endpoint you can update a promoter campaign. \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/promoter_campaigns/{id}`</Tip>"
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: Promoter campaign ID. This ID is not the promoter’s ID or the campaign’s ID. It’s the linking record that defines the promoter’s participation in that campaign. You can find this id in each object in the promoter_campaigns array when you get the details of the promoter.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ref_token:
                  type: string
                state:
                  type: string
                  enum:
                  - pending
                  - accepted
                  - rejected
                  - blocked
                  - inactive
                coupon:
                  type: string
                display_coupon:
                  type: string
                direct_url:
                  type: string
                rewards_for_promoters:
                  type: array
                  items:
                    $ref: '#/components/schemas/RewardConfig'
                rewards_for_referrals:
                  type: array
                  items:
                    $ref: '#/components/schemas/RewardConfig'
                promoter_rewards_customized:
                  type: boolean
                referral_rewards_customized:
                  type: boolean
      responses:
        '200':
          description: Updated promoter campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoterCampaign'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/{id}/referral_links:
    get:
      summary: Get promoter campaign referral links
      operationId: getReferralLinksAssociatedWithThisPromoterCampaign
      description: With this endpoint you can get the referral links associated with this promoter campaign. <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns/{id}/referral_links`</Tip>
      tags:
      - Promoter Campaigns
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: Promoter campaign ID
      responses:
        '200':
          description: List of referral links
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReferralLink'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /company/promoter_campaigns/{id}/chart_data:
    get:
      summary: Get data used for chart
      tags:
      - Promoter Campaigns
      operationId: getPromoterCampaignChartData
      description: With this endpoint you can get the data used for charts.<Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/promoter_campaigns/{id}/chart_data`</Tip>
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: Promoter campaign ID. This ID is not the promoter’s ID or the campaign’s ID. It’s the linking record that defines the promoter’s participation in that campaign. You can find this id in each object in the promoter_campaigns array when you get the details of the promoter.
      - in: query
        name: period_from
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: period_to
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: selection
        required: true
        schema:
          type: string
          enum:
          - revenue
          - clicks
          - referrals
          - customers
          - cancellations
      - in: query
        name: with_totals
        required: false
        schema:
          type: boolean
        description: If true, it will also return the totals for the period
      responses:
        '200':
          description: Chart data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartData'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PromoterCampaign:
      type: object
      properties:
        id:
          type: integer
        campaign_id:
          type: integer
        promoter_id:
          type: integer
        created_at:
          type: string
          format: date-time
        promoter:
          $ref: '#/components/schemas/Promoter'
        campaign:
          $ref: '#/components/schemas/Campaign'
        state:
          type: string
          enum:
          - pending
          - accepted
          - rejected
          - blocked
          - inactive
        stats:
          type: object
          properties:
            clicks_count:
              type: integer
            referrals_count:
              type: integer
            sales_count:
              type: integer
            customers_count:
              type: integer
            revenue_amount:
              type: number
        coupon:
          type: string
        display_coupon:
          type: string
        ref_token:
          type: string
        ref_link:
          type: string
        is_customized:
          type: boolean
        direct_url:
          type: string
        referral_rewards_customized:
          type: boolean
        promoter_rewards_customized:
          type: boolean
        rewards_for_promoters:
          type: array
          items:
            $ref: '#/components/schemas/Reward'
        rewards_for_referrals:
          type: array
          items:
            $ref: '#/components/schemas/Reward'
        promo_codes:
          type: array
          items:
            type: string
    Promoter:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
        name:
          type: string
    Campaign:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        color:
          type: string
    ChartData:
      type: object
      properties:
        period_from:
          type: string
          format: date
        period_to:
          type: string
          format: date
        selection:
          type: string
          enum:
          - revenue
          - clicks
          - referrals
          - customers
          - cancellations
        selection_items:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              value:
                type: number
        group_by:
          type: string
    RewardConfig:
      type: object
      required:
      - apply_on
      - product_ids
      - reward_id
      properties:
        apply_on:
          type: string
          enum:
          - monthly
          - yearly
          - one_time
          - all
          - specific
        product_ids:
          type: array
          items:
            type: integer
        reward_id:
          type: integer
    Reward:
      type: object
      properties:
        apply_on:
          type: string
        product_ids:
          type: array
          items:
            type: integer
        reward_id:
          type: integer
        reward:
          type: object
          properties:
            name:
              type: string
            promoter_reward_type:
              type: string
            hide_reward:
              type: boolean
            tier_level:
              type: integer
            coupon:
              type: string
        products:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
    Error:
      type: object
      properties:
        message:
          type: string
          example: Invalid user type
        code:
          type: string
          example: forbidden
    ReferralLink:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        url:
          type: string
        is_default:
          type: boolean
        source:
          type: string
          enum:
          - campaign
          - promoter
        sub_id:
          type: string
        campaign:
          $ref: '#/components/schemas/Campaign'
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: Account ID. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token