FirstPromoter Payouts API - 8 operation(s) on the admin (api/v2/company) surface, from FirstPromoter's own published OpenAPI definition (3.0.3) indexed in https://docs.firstpromoter.com/llms.txt.
openapi: 3.0.3
info:
title: FirstPromoter Admin Payouts API
description: API documentation for admin payouts endpoints
version: 1.0.0
servers:
- url: https://api.firstpromoter.com/api/v2/company
description: Production server
security:
- BearerAuth: []
paths:
/payouts:
get:
summary: Get all payouts
description: "With this endpoint you can list all payouts. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts`</Tip>"
operationId: getAdminPayouts
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: ids[]
in: query
description: Array of payout ids to get
required: false
schema:
type: array
items:
type: integer
- 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: filters[payments_batch_id]
in: query
description: Payment batches ids. Can be Integer or Array of Integers
required: false
schema:
oneOf:
- type: integer
- type: array
items:
type: integer
- name: filters[due_period]
in: query
description: Due period
required: false
schema:
type: string
enum:
- next
- overdue
- custom
- name: filters[period_start][from]
in: query
description: period_start starting from date
required: false
schema:
type: string
format: date
- name: filters[period_start][to]
in: query
description: period_start end at date
required: false
schema:
type: string
format: date
- name: filters[period_end][from]
in: query
description: period_end starting from date
required: false
schema:
type: string
format: date
- name: filters[period_end][to]
in: query
description: period_end end at date
required: false
schema:
type: string
format: date
- name: filters[payout_method]
in: query
description: Payout method
required: false
schema:
type: string
enum:
- paypal
- bank
- wise
- crypto
- custom
- dots
- not_set
- name: filters[promoter_id]
in: query
description: Promoter id
required: false
schema:
type: integer
- name: filters[only_payable]
in: query
description: Only payable payouts
required: false
schema:
type: boolean
- name: filters[group_ref]
in: query
description: Group reference
required: false
schema:
type: string
- name: filters[fraud_suspicions]
in: query
description: Fraud suspicions. Multiple values can be passed as an array. Send ['no_suspicion'] to filter promoters
with no fraud suspicions
required: false
schema:
type: array
items:
type: string
enum:
- same_ip_suspicion
- same_promoter_email
- ad_source
- no_suspicion
- name: sorting[amount]
in: query
description: The sort by amount direction
required: false
schema:
type: string
enum:
- asc
- desc
- name: sorting[period_start]
in: query
description: Period start
required: false
schema:
type: string
enum:
- asc
- desc
- name: sorting[period_end]
in: query
description: Period end
required: false
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Payout'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/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'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/due_stats:
get:
summary: Get due payout stats
description: "This endpoint returns statistics about due payouts. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/payouts/due_stats`</Tip>"
operationId: getAdminPayoutDueStats
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
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutDueStats'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/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'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/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'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/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'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/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'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/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'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
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
schemas:
Payout:
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 applied to the payout
unit:
type: string
description: Unit of the payout (e.g., cash)
period_start:
type: string
format: date-time
description: Start date of the period
period_end:
type: string
format: date-time
description: End date of the period
paid_at:
type: string
format: date-time
description: Date when the payout was paid
processing_started_at:
type: string
format: date-time
description: Date when the payout processing started
failed_at:
type: string
format: date-time
description: Date when the payout failed
error:
type: string
description: Error message if the payout failed
total_incl_tax:
type: number
format: float
description: Total amount including tax
created_at:
type: string
format: date-time
description: Date when the payout was created
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)
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
campaign:
type: object
properties:
id:
type: integer
description: ID of the campaign
name:
type: string
description: Name of the campaign
color:
type: string
description: Color of the campaign
PayoutStats:
type: object
properties:
meta:
type: object
properties:
net_payout_days:
type: integer
description: Number of days for net payout
payout_cycle:
type: string
description: Payout cycle (e.g., monthly)
min_payment:
type: integer
description: Minimum payment amount
min_paying_customers:
type: integer
description: Minimum number of paying customers
terms_description:
type: string
description: Description of payment terms
selected_payout_methods:
type: array
items:
type: string
description: List of selected payout methods
payout_method_options:
type: object
description: Options for payout methods
managed_payouts:
type: boolean
description: Whether payouts are managed by us (auto-payouts)
data:
type: object
properties:
by_paid_period:
type: array
items:
type: object
properties:
period_start:
type: string
format: date-time
description: Start date of the period
period_end:
type: string
format: date-time
description: End date of the period
promoters_count:
type: integer
description: Count of promoters
amounts:
type: object
additionalProperties:
type: number
description: Amounts by currency or unit
total_incl_tax:
type: number
description: Total amount including tax
by_status:
type: object
additionalProperties:
type: object
properties:
amounts:
type: object
additionalProperties:
type: number
total_incl_tax:
type: number
promoters_count:
type: integer
by_payout_method:
type: object
additionalProperties:
type: object
properties:
amounts:
type: object
additionalProperties:
type: number
total_incl_tax:
type: number
promoters_count:
type: integer
PayoutDueStats:
type: object
properties:
meta:
type: object
properties:
net_payout_days:
type: integer
description: Number of days for net payout
payout_cycle:
type: string
description: Payout cycle (e.g., monthly)
min_payment:
type: integer
description: Minimum payment amount
min_paying_customers:
type: integer
description: Minimum number of paying customers
terms_description:
type: string
description: Description of payment terms
selected_payout_methods:
type: array
items:
type: string
description: List of selected payout methods
payout_method_options:
type: object
description: Options for payout methods
managed_payouts:
type: boolean
description: Whether payouts are managed by us (auto-payouts)
data:
type: object
properties:
next:
type: object
properties:
promoters_count:
type: integer
description: Count of promoters
amounts:
type: object
additionalProperties:
type: number
description: Amounts by currency or unit
total_incl_tax:
type: number
description: Total amount including tax
due_date:
type: string
format: date
description: Due date for the next payout
period_end:
type: string
format: date
description: End date of the period
overdue:
type: object
properties:
promoters_count:
type: integer
description: Count of promoters
amounts:
type: object
additionalProperties:
type: number
description: Amounts by currency or unit
total_incl_tax:
type: number
description: Total amount including tax
due_date:
type: string
format: date
description: Due date for overdue payout
period_end:
type: string
format: date
description: End date of the period
custom:
type: object
properties:
promoters_count:
type: integer
description: Count of promoters
amounts:
type: object
additionalProperties:
type: number
description: Amounts by currency or unit
total_incl_tax:
type: number
description: Total amount including tax
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'
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
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:
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/firstpromoter/refs/heads/main/openapi/firstpromoter-v2-payouts-openapi.yml