> ## 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.
# Tracking sales and commissions
> Assign sales and commissions to your promoters. To track sales and generate commissions correctly, you need to use this API call each time a non-zero amount sale is processed in your system, even if it comes from a recurring charge or one-time charge. To avoid fraudulent sales, we don't use JS conversion pixels to track sales, which are very unreliable and can be easily faked. Instead, we use server-side tracking for all sales to ensure that a sale is tracked only when you actually receive money in your billing account.
To maintain the same standards with the API, we recommend making the sale API call (this call) only when you receive confirmation of the sale from your billing provider, such as from a webhook, an IPN, or a success response from an API charge call.
You just need to pass the sale amount (before taxes) and we'll take care of the rest. The commissions/rewards will be calculated based on that amount and the plan ID, in case you use the plan-level rewards feature. Using email or UID parameters, we identify the lead/customer who generated the sale, which also helps us determine the promoter who owns the reward/commission.
The lead is added to our system either by the client signup tracking script when the user signs up or by calling the signup API endpoint. There is also the option to bypass the signup tracking by using TID or ref_id parameters, which will create the lead and assign the sale in one go.
**If we don't find the lead in our system, then it means that the sale is not a referral sale, you'll get a 404 response. Also, if the promoter is banned, you'll get a 404 response. You don't have to identify which sale is from referrals and which is not; we'll take care of that.** **For zero-decimal** currencies like `JPY`, `amount` and `mrr` parameters should be sent as **whole values**.
**For other currencies**, `amount` and `mrr` parameter values should be in cents, i.e., you will need to **multiply the value by 100** before sending the request.**HTTP Request**
`POST https://api.firstpromoter.com/api/v2/track/sale`
## OpenAPI
````yaml openapi-v2-tracking POST /sale
openapi: 3.0.1
info:
title: FirstPromoter Tracking API V2
description: >-
Our tracking API allows companies to track any type of signups, sales,
cancellations and refunds for any billing provider, you are not limited to
our built-in integrations with Stripe, Chargebee, Recurly and Braintree.
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.firstpromoter.com/api/v2/track
security:
- BearerAuth: []
paths:
/sale:
post:
description: >-
Assign sales and commissions to your promoters. To track sales and
generate commissions correctly, you need to use this API call each time
a non-zero amount sale is processed in your system, even if it comes
from a recurring charge or one-time charge. To avoid fraudulent
sales, we don't use JS conversion pixels to track sales, which are very
unreliable and can be easily faked. Instead, we use server-side tracking
for all sales to ensure that a sale is tracked only when you actually
receive money in your billing account.
To maintain the same
standards with the API, we recommend making the sale API call (this
call) only when you receive confirmation of the sale from your billing
provider, such as from a webhook, an IPN, or a success response from an
API charge call.
You just need to pass the sale amount (before
taxes) and we'll take care of the rest. The commissions/rewards will be
calculated based on that amount and the plan ID, in case you use the
plan-level rewards feature. Using email or UID parameters, we
identify the lead/customer who generated the sale, which also helps us
determine the promoter who owns the reward/commission.
The
lead is added to our system either by the client signup tracking script
when the user signs up or by calling the signup API endpoint. There is
also the option to bypass the signup tracking by using TID or ref_id
parameters, which will create the lead and assign the sale in one
go.
**If we don't find the lead in our system, then it means
that the sale is not a referral sale, you'll get a 404 response. Also,
if the promoter is banned, you'll get a 404 response. You don't have to
identify which sale is from referrals and which is not; we'll take care
of that.** **For zero-decimal** currencies like `JPY`, `amount` and
`mrr` parameters should be sent as **whole values**.
**For
other currencies**, `amount` and `mrr` parameter values should be in
cents, i.e., you will need to **multiply the value by 100** before
sending the request.**HTTP Request**
`POST
https://api.firstpromoter.com/api/v2/track/sale`
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- event_id
- amount
properties:
email:
type: string
description: Email of the lead/sign-up. Required if uid is not provided.
uid:
type: string
description: >-
uid of the lead added on signup tracking. Required if email
is not provided.
event_id:
type: string
description: >-
Transaction or sale event ID. Required to avoid duplicate
sales.
amount:
type: integer
description: >-
The sale amount in cents. For zero-decimal currencies like
JPY, amount should be whole values.
quantity:
type: integer
description: Number of subscriptions/items. Optional if quantity is 1.
plan:
type: string
description: >-
Customer plan ID from billing provider. Used for plan-level
rewards.
currency:
type: string
description: >-
Required only if different from FirstPromoter settings
default currency.
mrr:
type: string
description: Monthly Recurring Revenue generated by the customer.
promo_code:
type: string
description: For promo code tracking.
tid:
type: string
description: Visitor tracking ID from _fprom_tid cookie.
ref_id:
type: string
description: Referral ID of the promoter.
skip_email_notification:
type: boolean
description: Set true to skip email notifications. Default is false.
oneOf:
- required:
- email
- required:
- uid
responses:
'200':
description: Sale tracked successfully
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 45831949
etype:
type: string
example: sale
sale_amount:
type: integer
example: 2000
original_sale_amount:
type: integer
example: 2000
original_sale_currency:
type: string
nullable: true
example: null
event_id:
type: string
nullable: true
example: null
plan_id:
type: string
nullable: true
example: null
billing_period:
type: string
nullable: true
example: null
created_at:
type: string
format: date-time
example: '2025-04-25T09:39:42.289Z'
referral:
type: object
properties:
id:
type: integer
example: 29203686
email:
type: string
example: testme@test1.com
uid:
type: string
nullable: true
example: null
commissions:
type: array
items:
type: object
properties:
id:
type: integer
example: 13533003
status:
type: string
example: approved
metadata:
type: object
example: {}
is_self_referral:
type: boolean
example: false
commission_type:
type: string
example: sale
created_by_user_email:
type: string
nullable: true
example: null
created_by_user_at:
type: string
nullable: true
example: null
sale_amount:
type: integer
example: 2000
original_sale_amount:
type: integer
example: 2000
original_sale_currency:
type: string
nullable: true
example: null
event_id:
type: string
nullable: true
example: null
plan_id:
type: string
nullable: true
example: null
tier:
type: integer
example: 1
internal_note:
type: string
nullable: true
example: null
external_note:
type: string
nullable: true
example: null
unit:
type: string
example: cash
fraud_check:
type: string
example: no_suspicion
amount:
type: integer
example: 400
is_paid:
type: boolean
example: false
is_split:
type: boolean
example: false
created_at:
type: string
format: date-time
example: '2025-04-25T09:39:42Z'
status_updated_at:
type: string
nullable: true
example: null
promoter_campaign:
type: object
properties:
id:
type: integer
example: 14850130
campaign_id:
type: integer
example: 28004
promoter_id:
type: integer
example: 8262622
created_at:
type: string
format: date-time
example: '2025-01-16T18:16:41Z'
promoter:
type: object
properties:
id:
type: integer
example: 8262622
email:
type: string
example: test@promoter.com
name:
type: string
example: Test Promoter
campaign:
type: object
properties:
id:
type: integer
example: 28004
name:
type: string
example: Quinn Ramirez
color:
type: string
example: '#EC4899'
referral:
type: object
properties:
id:
type: integer
example: 29203686
email:
type: string
example: testme@test1.com
uid:
type: string
nullable: true
example: null
reward:
type: object
properties:
id:
type: integer
example: 157427
name:
type: string
example: 20% recurring commission
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Error. Amount blank or invalid.
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
Referral corresponding to email or uid parameter not found
or promoter is banned.
code:
type: string
example: not_found
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
The 'sale' event with the id 'test_sale_12340987' already
exists.
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
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
````