FirstPromoter Tracking API - 4 operation(s) on the server-side tracking (api/v2/track) surface, from FirstPromoter's own published OpenAPI definition (3.0.1) indexed in https://docs.firstpromoter.com/llms.txt.
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:
/signup:
post:
description: Capture a lead when they sign-up or fill an optin form. This endpoint is used to track leads and sign-ups.
It's not for tracking the actual sales and commissions. <br/> <br/> Sign-ups are tracked as leads in FirstPromoter
so when a person referred by the promoter/affiliate signs up, a new referral should be added inside FirstPromoter
**(you can see them inside the `Referrals` section as `Leads`)**. <br/><br/><Tip>The recommended way to do this is
to grab the `_fprom_tid` **(_fprom_track for accounts created prior to April 2021)** cookie value(which keeps the
tracking id and referral identification) on your server and send it along with the sign-up data through the tid parameter.
<br/><br/> **Alternative:** In some special cases, you can refer sign ups directly to a promoter, by passing the referral
id through ref_id parameter. Be careful when using this because the referral id can be modified by the promoter by
default, however you can disable that from the campaign configuration page.</Tip><Tip>**HTTP Request** <br/>`POST
https://api.firstpromoter.com/api/v2/track/signup`</Tip>
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
description: Email of the lead/sign-up. Required if uid is not provided.
uid:
type: string
description: ID to match the sale with the lead if the email can be changed before the first sale. Required
if email is not provided.
tid:
type: string
description: Visitor tracking ID. It's set when the visitor tracking script tracks the referral visit on
our system. The value is found inside _fprom_tid cookie. Required if ref_id is not provided.
ref_id:
type: string
description: Default referral id of the promoter. Use this only when you want to assign the lead to a specific
promoter. Required if tid is not provided.
ip:
type: string
description: IP of the visitor who generated the sign up. It's used for fraud analysis.
created_at:
type: string
description: ISO date string of the date of the signup event
skip_email_notification:
type: boolean
description: Set this to true to skip email notifications. Default is false.
oneOf:
- required:
- email
- required:
- uid
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
description: Successful signup response
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 45831611
etype:
type: string
example: signup
sale_amount:
type: integer
nullable: true
example: null
original_sale_amount:
type: integer
nullable: true
example: null
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:29:51.973Z'
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: {}
example: []
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Error. Email and uid can not be blank!
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Visitor invalid, not found or you are trying to use the signup tracking test via API which doesn't
work on API calls.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
transaction_id:
type: string
example: there is already a signup event registered on this lead
/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. <Note>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. <br/><br/>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.<br/><br/>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.</Note> 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. <br/><br/>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.<br/><br/>**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.** <Tip>**For zero-decimal** currencies like `JPY`, `amount` and `mrr` parameters
should be sent as **whole values**. <br/><br/>**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.</Tip><Tip>**HTTP Request**
<br/>`POST https://api.firstpromoter.com/api/v2/track/sale`</Tip>
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
'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
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Error. Amount blank or invalid.
'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.
/refund:
post:
description: The refund call is similar to the sale call. It works the same way, except that it generates negative commissions.
<Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/track/refund`</Tip>
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 refund event ID. Required to avoid generating duplicate refunds.
amount:
type: string
description: The refund amount in cents. Used to calculate negative commissions/rewards.
currency:
type: string
description: This field is only required if the currency of the sale/refund is not the same as the one set
on FirstPromoter settings. We'll automatically convert the amount from this currency to the default one
set on your FirstPromoter account.
quantity:
type: string
description: Number of subscriptions/items refunded. Optional if quantity is 1.
sale_event_id:
type: string
description: The event id of the sale for which the refund is processed. Should match the event_id from
the sales tracking API call. Required for accurate tracking of multiple products or changing commission
levels.
skip_email_notification:
type: boolean
description: Set true to skip email notifications. Default is false.
oneOf:
- required:
- email
- required:
- uid
responses:
'200':
description: Success response
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 33847726
type:
type: string
example: refund
amount_cents:
type: integer
example: -1000
reward:
type: object
properties:
id:
type: integer
example: 10940148
status:
type: string
example: approved
amount:
type: integer
example: -200
unit:
type: string
example: cash
created_at:
type: string
format: date-time
example: '2024-09-11T14:36:01.016Z'
lead:
$ref: '#/components/schemas/Lead'
event_id:
type: string
example: test_sale_12340987_refund
conversion_amount:
type: integer
example: -1000
tier_level:
type: integer
example: 1
split_type:
type: string
nullable: true
example: null
lead:
$ref: '#/components/schemas/Lead'
promoter:
$ref: '#/components/schemas/Promoter'
'204':
description: No Content
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Error. Amount blank or invalid.
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The 'refund' event with the id 'test_sale_12340987_refund' already exists.
/cancellation:
post:
description: This call will mark the customer as cancelled and will decrease the MRR generated by them. <Tip>**HTTP
Request** <br/>`POST https://api.firstpromoter.com/api/v2/track/cancellation`</Tip>
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
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.
oneOf:
- required:
- email
- required:
- uid
responses:
'200':
description: Success response
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 33848911
type:
type: string
example: cancellation
amount_cents:
type: integer
nullable: true
example: null
reward:
type: object
nullable: true
example: null
lead:
$ref: '#/components/schemas/Lead'
promoter:
$ref: '#/components/schemas/Promoter'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Error. Email and uid can not be blank!
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:
Promoter:
type: object
properties:
id:
type: integer
description: ID of the promoter
example: 3920164
status:
type: string
description: Status of the promoter
example: active
cust_id:
type: string
example: ''
email:
type: string
description: Email of the promoter
example: peluwydo@mailinator.com
created_at:
type: string
format: date-time
description: ISO date of when the promoter was created
example: '2022-04-26T15:28:24.800Z'
temp_password:
type: string
description: Temporary password created for the promoter
nullable: true
example: xxxxxxxxxx
default_promotion_id:
type: integer
example: 4210919
pref:
type: string
example: db1znwe
default_ref_id:
type: string
description: Default referral id of the promoter
example: 8yi2epelut
note:
type: string
description: A note/description of promoter
nullable: true
example: This is a note
w8_form_url:
type: string
description: Url of the w8 form
nullable: true
example: null
w9_form_url:
type: string
description: Url of the w9 form
nullable: true
example: null
parent_promoter_id:
type: integer
description: Parent promoter id
example: 577918
earnings_balance:
type: object
description: Earning balance of the promoter
properties:
cash:
type: integer
example: 50744
current_balance:
type: object
description: Current balance of the promoter
properties:
cash:
type: integer
example: 20044
paid_balance:
type: object
description: Paid balance of the promoter
properties:
cash:
type: integer
example: 30700
auth_token:
type: string
description: Authentication token generated when the promoter was created
example: xxxxxxxxxxxxxx
Lead:
type: object
properties:
id:
type: integer
example: 20738339
state:
type: string
example: cancelled
email:
type: string
example: hello@testmintli.com
uid:
type: string
nullable: true
example: null
customer_since:
type: string
format: date-time
example: '2024-09-11T14:22:12.160Z'
cancelled_at:
type: string
format: date-time
example: '2024-09-11T15:07:46.174Z'
plan_name:
type: string
nullable: true
example: null
suspicion:
type: string
example: no_suspicion
username:
type: string
nullable: true
example: null
website:
type: string
nullable: true
example: null
created_at:
type: string
format: date-time
example: '2024-09-09T16:22:44.168Z'
split_promotion_id:
type: string
nullable: true
example: null
custom_fields:
type: string
nullable: true
example: null
split_percentage_value:
type: string
nullable: true
example: null
visitor_sub_id:
type: string
nullable: true
example: null
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
accountId:
type: apiKey
in: header
name: ACCOUNT-ID
description: Your FirstPromoter Account ID. You can find this in the Settings → Integrations section of your dashboard.