FirstPromoter Payouts API

openapi: 3.2.0
info:
  title: Firstpromoter Payouts API
  version: '1.0'
  description: 'Operations tagged Payouts across 3 of this provider''s published API definitions: firstpromoter-v2-affiliate-payouts-openapi.yml, firstpromoter-v2-commissions-openapi.yml, firstpromoter-v2-payouts-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: Payouts
paths:
  /payouts:
    get:
      summary: Get all payouts
      tags:
      - Payouts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by 'promoter.profile.first_name`, `promoter.profile.last_name`, `promoter.user.email`
        schema:
          type: string
      - name: filters[status]
        in: query
        description: Status filter
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
      - name: filters[campaign_id]
        in: query
        description: Campaign ids filter
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: filters[payments_batch_id]
        in: query
        description: Payment batches ids filter
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: filters[due_period]
        in: query
        description: Due period filter
        schema:
          type: string
          enum:
          - next
          - overdue
          - custom
      - name: filters[period_start]
        in: query
        description: Period start filter. Send "not_set" for returning the ones with period_start == null
        schema:
          type: string
          format: date
      - name: filters[period_end]
        in: query
        description: Period end filter. Send "not_set" for returning the ones with period_end == null
        schema:
          type: string
          format: date
      - name: filters[payout_method]
        in: query
        description: Payout method filter
        schema:
          type: string
          enum:
          - paypal
          - bank
          - wise
          - crypto
          - custom
          - dots
          - not_set
      - name: filters[group_ref]
        in: query
        description: Group ref filter
        schema:
          type: string
      responses:
        '200':
          description: List of payouts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payout'
                  meta:
                    $ref: '#/components/schemas/PayoutMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /payouts/due_stats:
    get:
      summary: Get due payout stats
      tags:
      - Payouts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Payout stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/PayoutMeta'
                  data:
                    type: object
                    properties:
                      next:
                        $ref: '#/components/schemas/PayoutStats'
                      overdue:
                        $ref: '#/components/schemas/PayoutStats'
                      custom:
                        $ref: '#/components/schemas/PayoutStats'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /payouts/export:
    get:
      summary: Export payouts
      tags:
      - Payouts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params
        schema:
          type: string
      - $ref: '#/components/parameters/filters'
      responses:
        '200':
          description: Payouts exported successfully
          content:
            text/csv:
              schema:
                type: string
        '202':
          description: Export is being processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /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:
      - Payouts
      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
  /payouts/stats:
    get:
      summary: Get payout stats
      description: "This endpoint returns statistics about payouts. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts/stats`</Tip>"
      operationId: getAdminPayoutStats
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: stats_by[paid_period]
        in: query
        description: Shows the stats by payout period only for paid payouts
        required: false
        schema:
          type: boolean
      - name: stats_by[status]
        in: query
        description: Shows the stats by status (pending, failed, processing, completed)
        required: false
        schema:
          type: boolean
      - name: stats_by[payout_method]
        in: query
        description: Shows the stats by payout method
        required: false
        schema:
          type: boolean
      - name: filters[status]
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
      - name: filters[campaign_id]
        in: query
        description: Campaign ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutStats_2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
      tags:
      - Payouts
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
      description: Production server
  /payouts/group_by_promoters:
    get:
      summary: Get all payouts grouped by promoters
      description: "This endpoint returns all payouts but grouped by promoters. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts/group_by_promoters`</Tip>"
      operationId: getAdminPayoutsGroupedByPromoters
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: q
        in: query
        description: Search params. Searches by 'promoter.profile.first_name`, `promoter.profile.last_name`, `promoter.user.email`
        required: false
        schema:
          type: string
      - name: filters[status]
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
      - name: filters[campaign_id]
        in: query
        description: Campaign ids. Can be Integer or Array of Integers
        required: false
        schema:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      - name: include_payout_method_details
        in: query
        description: Set it true to include the payout_method_details
        required: false
        schema:
          type: boolean
      - name: filters[min_payment]
        in: query
        description: Filters payouts by the minimum payment amount possible
        required: false
        schema:
          type: integer
      - name: filters[invoiceable]
        in: query
        description: Filters payouts by invoiceable
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_set
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutsGroupedByPromoters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
      tags:
      - Payouts
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
      description: Production server
  /payouts/create_payments_batch:
    post:
      summary: Create payments batch
      description: "This endpoint creates a new payments batch. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/payouts/create_payments_batch`</Tip>"
      operationId: createPaymentsBatch
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                method:
                  type: string
                  enum:
                  - paypal
                  - bank
                  - wise
                  - crypto
                  - dots
                  description: Payment method
              required:
              - method
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsBatch'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
      tags:
      - Payouts
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
      description: Production server
  /payouts/mark_as_paid:
    post:
      summary: Mark payouts as paid
      description: "Marks selected payouts as paid \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/payouts/mark_as_paid`</Tip>"
      operationId: markPayoutsAsPaid
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
              required:
              - ids
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '202':
          description: Accepted (Processing in background)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
      tags:
      - Payouts
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
      description: Production server
  /payouts/mark_as_unpaid:
    post:
      summary: Mark payouts as unpaid
      description: "Marks selected payouts as unpaid \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/payouts/mark_as_unpaid`</Tip>"
      operationId: markPayoutsAsUnpaid
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
              required:
              - ids
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '202':
          description: Accepted (Processing in background)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
      tags:
      - Payouts
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
      description: Production server
  /payouts/destroy:
    delete:
      summary: Delete payouts
      description: "Deletes selected payouts \n <Tip>**HTTP Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/payouts/destroy`</Tip>"
      operationId: deletePayouts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  $ref: '#/components/schemas/Ids'
              required:
              - ids
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '202':
          description: Accepted (Processing in background)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActionResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
      tags:
      - Payouts
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
      description: Production server
components:
  parameters:
    filters:
      name: filters
      in: query
      description: Filter parameters
      schema:
        type: object
        properties:
          status:
            type: string
            enum:
            - pending
            - completed
            - failed
            - processing
            - cancelled
          campaign_id:
            oneOf:
            - type: integer
            - type: array
              items:
                type: integer
          payments_batch_id:
            oneOf:
            - type: integer
            - type: array
              items:
                type: integer
          due_period:
            type: string
            enum:
            - next
            - overdue
            - custom
          period_start:
            type: string
            format: date
          period_end:
            type: string
            format: date
          payout_method:
            type: string
            enum:
            - paypal
            - bank
            - wise
            - crypto
            - custom
            - dots
            - not_set
          group_ref:
            type: string
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: Account identifier that specifies which account is making the request
      schema:
        type: string
        example: acc_123456
    AccountId_2:
      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
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    Payout:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
        amount:
          type: number
          format: float
        payments_batch_id:
          type: integer
        tax_rate:
          type: number
          format: float
        unit:
          type: string
        period_start:
          type: string
          format: date
        period_end:
          type: string
          format: date
        paid_at:
          type: string
          format: date-time
        processing_started_at:
          type: string
          format: date-time
        failed_at:
          type: string
          format: date-time
        error:
          type: string
        total_incl_tax:
          type: number
          format: float
        created_at:
          type: string
          format: date-time
        payout_method:
          type: object
        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
    PayoutStats:
      type: object
      properties:
        promoters_count:
          type: integer
        amounts:
          type: object
          additionalProperties:
            type: number
        total_incl_tax:
          type: number
        due_date:
          type: string
          format: date
        period_end:
          type: string
          format: date
    PayoutMeta:
      type: object
      properties:
        net_payout_days:
          type: integer
        payout_cycle:
          type: string
        min_payment:
          type: number
          format: float
        min_paying_customers:
          type: integer
        terms_description:
          type: string
        selected_payout_methods:
          type: array
          items:
            type: string
        payout_method_options:
          type: object
        managed_payouts:
          type: boolean
    BatchActionResult:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: ID of the batch action
            status:
              type: string
              enum:
              - pending
              - completed
              - failed
              description: Status of the batch action
            total:
              type: integer
              description: Total number of items
            selected_total:
              type: integer
              description: Number of selected items
            processed_count:
              type: integer
              description: Number of processed items
            failed_count:
              type: integer
              description: Number of failed items
            action_label:
              type: string
              description: Label of the action
            created_at:
              type: string
              format: date-time
              description: When the action was created
            updated_at:
              type: string
              format: date-time
              description: When the action was last updated
            meta:
              type: object
              description: Meta information about the action
            progress:
              type: integer
              description: Progress of the action (0-100)
            processing_errors:
              type: array
              items:
                type: object
              description: List of processing errors
        meta:
          type: object
          properties:
            total:
              type: number
              description: Total amount
            promoters_count:
              type: integer
              description: Count of promoters
            total_incl_tax:
              type: number
              description: Total amount including tax
            all_promoters_count:
              type: integer
              description: Count of all promoters
    PaymentsBatch:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: ID of the payments batch
            status:
              type: string
              enum:
              - awaiting_confirmation
              - pending
              - processing
              - completed
              - failed
              description: Status of the payments batch
            ext_reference:
              type: string
              description: External reference
            ext_id:
              type: string
              description: External ID
            scheduled_at:
              type: string
              format: date-time
              description: When the batch is scheduled
            processing_started_at:
              type: string
              format: date-time
              description: When processing started
            completed_at:
              type: string
              format: date-time
              description: When the batch was completed
            is_payable:
              type: boolean
              description: Whether the batch is payable
            is_retriable:
              type: boolean
              description: Whether the batch can be retried
            is_payment_otp_required:
              type: boolean
              description: Whether OTP is required for payment
            total:
              type: number
              description: Total amount
            promoters_count:
              type: integer
              description: Count of promoters
            error:
              type: string
              description: Error message if the batch failed
        meta:
          type: object
          properties:
            failed:
              type: array
              items:
                type: object
              description: List of failed items
    Error_2:
      type: object
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
      required:
      - message
      - code
    PayoutsGroupedByPromoters:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              promoter:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID of the promoter
                  email:
                    type: string
                    description: Email of the promoter
                  name:
                    type: string
                    description: Name of the promoter
                  invoice_details_status:
                    type: string
                    description: Status of invoice details
                  fraud_suspicions:
                    type: array
                    items:
                      type: string
                    description: List of fraud suspicions
                  profile:
                    type: object
                    properties:
                      invoice_details_validation_errors:
                        type: object
                        description: Validation errors for invoice details
              payout_method:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID of the payout method
                  method:
                    type: string
                    description: Payout method name
                  date_added:
                    type: string
                    format: date-time
                    description: Date when the payout method was added
                  is_disabled:
                    type: boolean
                    description: Whether the payout method is disabled
                  meta:
                    type: object
                    description: Additional meta information
                  is_selected:
                    type: boolean
                    description: Whether the payout method is selected
                  details:
                    type: object
                    description: Details about the payout method
                  managed_payouts:
                    type: boolean
                    description: Whether payouts are managed by us (auto-payouts)
              payouts:
                type: array
                items:
                  $ref: '#/components/schemas/Payout_2'
              is_amount_payable:
                type: boolean
                description: Whether the amount is payable
              payout_ids:
                type: array
                items:
                  type: integer
                description: List of payout IDs
              amount:
                type: number
                description: Total amount
              total_incl_tax:
                type: number
                description: Total amount including tax
        meta:
          type: object
          properties:
            total:
              type: number
              description: Total amount
            promoters_count:
              type: integer
              description: Count of promoters
            total_incl_tax:
              type: number
              description: Total amount including tax
            due_date:
              type: string
              format: date
              description: Due date
            period_end:
              type: string
              format: date
              description: End date of the period
    Payout_2:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the payout
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
          - processing
          - cancelled
          description: Status of the payout
        amount:
          type: number
          format: float
          description: Amount of the payout
        payments_batch_id:
          type: integer
          description: ID of the payments batch
        tax_rate:
          type: number
          format: float
          description: Tax rate applie

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