> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstpromoter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a commission
> With this endpoint you can create a commission.
**HTTP Request**
`POST https://api.firstpromoter.com/api/v2/company/commissions`
## OpenAPI
````yaml openapi-v2-commissions post /commissions
openapi: 3.0.1
info:
title: FirstPromoter Commissions API
version: 2.0.0
description: API for managing commissions in FirstPromoter
servers:
- url: https://api.firstpromoter.com/api/v2/company
security:
- BearerAuth: []
paths:
/commissions:
post:
tags:
- Commissions
summary: Create a commission
description: |-
With this endpoint you can create a commission.
**HTTP Request**
`POST https://api.firstpromoter.com/api/v2/company/commissions`
parameters:
- $ref: '#/components/parameters/AccountId'
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'
'401':
description: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
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
schemas:
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
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
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'
Commission:
type: object
properties:
id:
type: integer
description: Commission ID
status:
type: string
enum:
- pending
- approved
- denied
description: Current status of the commission
metadata:
type: object
description: Additional metadata about the commission
is_self_referral:
type: boolean
nullable: true
description: Whether this is a self-referral
commission_type:
type: string
enum:
- sale
- custom
description: Type of commission
created_by_user_email:
type: string
nullable: true
description: Email of the user who created the commission
created_by_user_at:
type: string
format: date-time
nullable: true
description: Timestamp when the user created the commission
sale_amount:
type: integer
description: Amount of the sale
original_sale_amount:
type: integer
description: Original amount of the sale
original_sale_currency:
type: string
nullable: true
description: Currency of the original sale
event_id:
type: string
nullable: true
description: ID of the event that generated the commission
plan_id:
type: string
nullable: true
description: Plan ID associated with the commission
tier:
type: integer
description: Reward tier
internal_note:
type: string
nullable: true
description: Internal note visible only to the team
external_note:
type: string
nullable: true
description: External note visible to the promoter
unit:
type: string
enum:
- cash
- credits
- points
- free_months
- mon_discount
- discount_per
description: Unit type for the reward
fraud_check:
type: string
nullable: true
enum:
- no_suspicion
- same_ip_suspicion
- same_promoter_email
- ad_source
description: Result of fraud check
amount:
type: integer
description: Commission amount
is_paid:
type: boolean
description: Whether the commission has been paid
is_split:
type: boolean
description: Whether the commission is split among multiple promoters
created_at:
type: string
format: date-time
description: Creation timestamp
status_updated_at:
type: string
format: date-time
nullable: true
description: Last status update timestamp
promoter_campaign:
type: object
properties:
id:
type: integer
description: Promoter campaign ID
campaign_id:
type: integer
description: Campaign ID
promoter_id:
type: integer
description: Promoter ID
created_at:
type: string
format: date-time
description: Creation timestamp
promoter:
type: object
properties:
id:
type: integer
description: Promoter ID
email:
type: string
description: Promoter email
name:
type: string
description: Promoter name
campaign:
type: object
properties:
id:
type: integer
description: Campaign ID
name:
type: string
description: Campaign name
color:
type: string
nullable: true
description: Campaign color
referral:
type: object
nullable: true
properties:
id:
type: integer
description: Referral ID
email:
type: string
description: Referral email
uid:
type: string
description: Referral UID
reward:
type: object
properties:
id:
type: integer
description: Reward ID
name:
type: string
description: Reward name
split_details:
type: object
nullable: true
description: >-
Commission split details from the associated referral, when the
referral is shared between promoters
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
API key passed as a Bearer token in the Authorization header. You can
find your API Key on Your FirstPromoter Dashboard. Navigate to Settings
→ Integrations section → Manage API Keys
````