FirstPromoter Commissions API

openapi: 3.2.0
info:
  title: Firstpromoter Commissions API
  version: '1.0'
  description: 'Operations tagged Commissions across 2 of this provider''s published API definitions: firstpromoter-v2-affiliate-commissions-openapi.yml, firstpromoter-v2-commissions-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.firstpromoter.com/api/v2/affiliate
- url: https://api.firstpromoter.com/api/v2/company
security:
- BearerAuth: []
tags:
- name: Commissions
paths:
  /commissions:
    get:
      summary: Get all commissions
      description: "Return all commissions \n <Tip>**HTTP Request** <br/>` GET  https://api.firstpromoter.com/api/v2/affiliate/commissions`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by initial_tier_event.transaction_id, lead.email, lead.uid
        required: false
        schema:
          type: string
      - name: filters[status]
        in: query
        description: Status filter
        required: false
        schema:
          type: string
          enum:
          - pending
          - approved
          - denied
      - name: filters[paid]
        in: query
        description: Paid filter
        required: false
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
      - name: filters[sale_amount][from]
        in: query
        description: Sale amount from
        required: false
        schema:
          type: integer
      - name: filters[sale_amount][to]
        in: query
        description: Sale amount to
        required: false
        schema:
          type: integer
      - name: filters[amount][from]
        in: query
        description: Amount from
        required: false
        schema:
          type: integer
      - name: filters[amount][to]
        in: query
        description: Amount to
        required: false
        schema:
          type: integer
      - name: filters[created_at][from]
        in: query
        description: Created at start date
        required: false
        schema:
          type: string
          format: date
      - name: filters[created_at][to]
        in: query
        description: Created at end date
        required: false
        schema:
          type: string
          format: date
      - name: filters[campaign_id]
        in: query
        description: Campaign ids
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: filters[payout_id]
        in: query
        description: Payout ids
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: filters[due_period]
        in: query
        description: Due period filter
        required: false
        schema:
          type: string
          enum:
          - next
          - overdue
          - custom
      - name: filters[promoter_id]
        in: query
        description: Promoter id
        required: false
        schema:
          type: integer
      - name: filters[first_commission]
        in: query
        description: First commission
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: filters[refunded]
        in: query
        description: Refunded reward
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - 'yes'
          - 'no'
      - name: filters[fraud_check]
        in: query
        description: Referral fraud check (suspicion)
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - no_suspicion
            - same_ip_suspicion
            - same_promoter_email
            - ad_source
      - name: filters[plan_id]
        in: query
        description: Plan id
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: sorting[sale_amount]
        in: query
        description: Sort by sale amount
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sorting[amount]
        in: query
        description: Sort by amount
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sorting[created_at]
        in: query
        description: Sort by created_at
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sorting[referral]
        in: query
        description: Sort by referral
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Commission'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a commission
      description: "With this endpoint you can create a commission. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommissionCreate'
      responses:
        '200':
          description: Successfully retrieved commissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Commission_2'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /commissions/export:
    get:
      summary: Export all commissions
      description: "Export all commissions \n <Tip>**HTTP Request** <br/>` GET  https://api.firstpromoter.com/api/v2/affiliate/commissions/export`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/CommissionFilters'
      responses:
        '200':
          description: Successful response
          content:
            text/csv:
              schema:
                type: string
        '202':
          description: Processing request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: We are processing your request. You will receive an email shortly.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /commissions/{id}:
    put:
      summary: Update a commission
      description: "With this endpoint you can update a commission. \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/commissions/{id}`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Id of the commission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommissionUpdate'
      responses:
        '200':
          description: Commission updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Commission_2'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Commission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
  /commissions/approve:
    post:
      summary: Approve commissions
      description: "With this endpoint you can approve commissions. \n <Note>If there are more than __5__ ids on the __ids__ param/field, the action will be processed asynchronously. The response for the batch status will most likely be `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note> \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions/approve`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
  /commissions/deny:
    post:
      summary: Deny commissions
      description: "With this endpoint you can deny commissions. \n <Note>If there are more than __5__ ids on the __ids__ param/field, the action will be processed asynchronously. The response for the batch status will most likely be `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note> \n  <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions/deny`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
  /commissions/mark_fulfilled:
    post:
      summary: Mark nonmonetary commissions as fulfilled
      description: "With this endpoint you can mark nonmonetary commissions as fulfilled. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions/mark_fulfilled`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
  /commissions/mark_unfulfilled:
    post:
      summary: Mark nonmonetary commissions as unfulfilled
      description: "With this endpoint you can mark nonmonetary commissions as unfulfilled. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions/mark_unfulfilled`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
  /commissions/destroy:
    delete:
      summary: Delete commissions
      description: "With this endpoint you can delete commissions. \n <Tip>**HTTP Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/commissions/destroy`</Tip>"
      tags:
      - Commissions
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchActionRequest'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - completed
                      description: Status of the batch operation (always completed for synchronous operations)
        '202':
          description: Batch operation accepted and processing
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BatchOperationResponse'
                - properties:
                    status:
                      type: string
                      enum:
                      - pending
                      description: Status of the batch operation (initially pending for asynchronous operations)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
  /commissions/generate_payouts:
    post:
      summary: Generate payouts for commissions
      description: "With this endpoint you can generate payouts for commissions. \n <Note>If there are more than __5__ ids on the __ids__ param/field, the action will be processed asynchronously. The response for the batch status will most likely be `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`</Note> \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/commissions/generate_payouts`</Tip>"
      tags:
      - Commissions
      operationId: generatePayouts
      parameters:
      - $ref: '#/components/parameters/AccountId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                  description: Commission IDs to generate payouts for. If there are more than __5__ ids on the __ids__ param/field, the action will be processed asynchronously. The response for the batch status will most likely be `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`.
              required:
              - ids
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Operation ID
                  status:
                    type: string
                    description: Status of the operation
                  total:
                    type: integer
                    description: Total number of commissions
                  selected_total:
                    type: integer
                    description: Number of selected commissions
                  processed_count:
                    type: integer
                    description: Number of processed commissions
                  failed_count:
                    type: integer
                    description: Number of failed operations
                  action_label:
                    type: string
                    description: Action identifier
                  created_at:
                    type: string
                    format: date-time
                    description: Creation timestamp
                  updated_at:
                    type: string
                    format: date-time
                    description: Last update timestamp
                  meta:
                    type: object
                    description: Additional metadata
                  progress:
                    type: number
                    description: Progress indicator (0-1)
                  processing_errors:
                    type: array
                    description: List of processing errors
        '401':
          description: Unauthorized - Missing or invalid bearer token
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
    Campaign:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        color:
          type:
          - string
          - 'null'
    Commission:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          enum:
          - pending
          - approved
          - denied
        external_note:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        status_updated_at:
          type:
          - string
          - 'null'
          format: date-time
        promoter_campaign:
          $ref: '#/components/schemas/PromoterCampaign'
        referral:
          $ref: '#/components/schemas/Referral'
        reward:
          $ref: '#/components/schemas/Reward'
        commission_type:
          type: string
          enum:
          - sale
          - custom
        sale_amount:
          type: number
        original_sale_amount:
          type: number
        original_sale_currency:
          type:
          - string
          - 'null'
        plan_id:
          type:
          - string
          - 'null'
        tier:
          type: integer
        unit:
          type: string
        amount:
          type: number
        is_paid:
          type: boolean
    PromoterCampaign:
      type: object
      properties:
        id:
          type: integer
        campaign_id:
          type: integer
        created_at:
          type: string
          format: date-time
        campaign:
          $ref: '#/components/schemas/Campaign'
    Reward:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    Referral:
      type:
      - object
      - 'null'
      properties:
        id:
          type: integer
        uid:
          type: string
        email:
          type: string
    CommissionCreate:
      oneOf:
      - title: Sale Commission
        type: object
        required:
        - commission_type
        - referral_id
        - sale_amount
        properties:
          commission_type:
            type: string
            enum:
            - sale
            description: The commission type
          referral_id:
            type: integer
            description: Referral id. Required for sale commission type.
          plan_id:
            type: integer
            description: One of the items id from price_ids
          sale_amount:
            type: integer
            description: Sale amount in cents. Required for sale commission type.
          event_id:
            type: string
            description: The ID of the event that generated the sale from billing provider
          event_date:
            type: string
            format: date
            description: The date of the event that generated the sale
          internal_note:
            type: string
            description: Internal note visible only by the team
          external_note:
            type: string
            description: External note visible by the promoter
          unit:
            type: string
            enum:
            - cash
            - credits
            - points
            - free_months
            - mon_discount
            - discount_per
            description: Set the reward unit type
          notify_promoter:
            type: boolean
            description: If true a notification email is sent to promoter if enabled on Emails section
          billing_period:
            type: string
            enum:
            - monthly
            - yearly
            - one_time
            description: The billing period of the event that generated the sale
      - title: Custom Commission
        type: object
        required:
        - commission_type
        - promoter_campaign_id
        - amount
        properties:
          commission_type:
            type: string
            enum:
            - custom
            description: The commission type
          promoter_campaign_id:
            type: integer
            description: PromoterCampaign id. Required for custom commission type. 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.
          amount:
            type: integer
            description: Commission amount in cents. Required for custom commission type.
          event_id:
            type: string
            description: The ID of the event that generated the sale from billing provider
          event_date:
            type: string
            format: date
            description: The date of the event that generated the sale
          internal_note:
            type: string
            description: Internal note visible only by the team
          external_note:
            type: string
            description: External note visible by the promoter
          unit:
            type: string
            enum:
            - cash
            - credits
            - points
            - free_months
            - mon_discount
            - discount_per
            description: Set the reward unit type
          notify_promoter:
            type: boolean
            description: If true a notification email is sent to promoter if enabled on Emails section
          billing_period:
            type: string
            enum:
            - monthly
            - yearly
            - one_time
            description: The billing period of the event that generated the sale
      discriminator:
        propertyName: commission_type
        mapping:
          sale: '#/components/schemas/CommissionCreate/oneOf/0'
          custom: '#/components/schemas/CommissionCreate/oneOf/1'
    BatchActionRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: integer
          description: Array of commission Ids. If there are more than __5__ ids on this param/field, the action will be processed asynchronously. The response for the batch status will most likely be `in_progress`. The available statuses are `pending`, `in_progress`, `completed`, `failed` and `stopped`
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    BatchOperationResponse:
      type: object
      properties:
        id:
          type: integer
          description: Batch ID
        status:
          type: string
          enum:
          - completed
          - pending
          - in_progress
          - failed
          - stopped
          description: Status of the batch operation
        total:
          type: integer
          description: Total number of items
        selected_total:
          type: integer
          description: Total number of selected items
        processed_count:
          type: integer
          description: Number of processed items
        failed_count:
          type: integer
          description: Number of failed operations
        action_label:
          type: string
          description: Label for the action
        created_at:
          type: string
          format: date-time
          description: Creation date of the batch operation
        updated_at:
          type: string
          format: date-time
          description: Last update date of the batch operation
        meta:
          type: object
          description: Additional metadata
        progress:
          type: integer
          description: Progress of the batch operation
        processing_errors:
          type: array
          items:
            type: string
          description: List of processing errors if any
    CommissionFilters:
      type: object
      properties:
        status:
          type: string
          enum:
          - pending
          - approved
          - denied
        paid:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Paid filter for monetary commissions
        fulfilled:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Fulfilled filter for non-monetary commissions
        sale_amount:
          type: object
          properties:
            from:
              type: integer
              description: Sale amount from
            to:
              type: integer
              description: Sale amount to
        amount:
          type: object
          properties:
            from:
              type: integer
              description: Amount from
            to:
              type: integer
              description: Amount to
        created_at:
          type: object
          properties:
            from:
              type: string
              format: date
              description: created_at start date
            to:
              type: string
              format: date
              description: created_at

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/firstpromoter/refs/heads/main/openapi/firstpromoter-commissions-api-openapi.yml