cURL
curl --request POST \
--url https://api.firstpromoter.com/api/v2/track/sale \
--header 'Account-ID: <account-id>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>",
"event_id": "<string>",
"amount": 123,
"uid": "<string>",
"quantity": 123,
"plan": "<string>",
"currency": "<string>",
"mrr": "<string>",
"promo_code": "<string>",
"billing_country": "US",
"tid": "<string>",
"ref_id": "<string>",
"skip_email_notification": true
}
'import requests
url = "https://api.firstpromoter.com/api/v2/track/sale"
payload = {
"email": "<string>",
"event_id": "<string>",
"amount": 123,
"uid": "<string>",
"quantity": 123,
"plan": "<string>",
"currency": "<string>",
"mrr": "<string>",
"promo_code": "<string>",
"billing_country": "US",
"tid": "<string>",
"ref_id": "<string>",
"skip_email_notification": True
}
headers = {
"Account-ID": "<account-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Account-ID': '<account-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: '<string>',
event_id: '<string>',
amount: 123,
uid: '<string>',
quantity: 123,
plan: '<string>',
currency: '<string>',
mrr: '<string>',
promo_code: '<string>',
billing_country: 'US',
tid: '<string>',
ref_id: '<string>',
skip_email_notification: true
})
};
fetch('https://api.firstpromoter.com/api/v2/track/sale', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.firstpromoter.com/api/v2/track/sale",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '<string>',
'event_id' => '<string>',
'amount' => 123,
'uid' => '<string>',
'quantity' => 123,
'plan' => '<string>',
'currency' => '<string>',
'mrr' => '<string>',
'promo_code' => '<string>',
'billing_country' => 'US',
'tid' => '<string>',
'ref_id' => '<string>',
'skip_email_notification' => true
]),
CURLOPT_HTTPHEADER => [
"Account-ID: <account-id>",
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.firstpromoter.com/api/v2/track/sale"
payload := strings.NewReader("{\n \"email\": \"<string>\",\n \"event_id\": \"<string>\",\n \"amount\": 123,\n \"uid\": \"<string>\",\n \"quantity\": 123,\n \"plan\": \"<string>\",\n \"currency\": \"<string>\",\n \"mrr\": \"<string>\",\n \"promo_code\": \"<string>\",\n \"billing_country\": \"US\",\n \"tid\": \"<string>\",\n \"ref_id\": \"<string>\",\n \"skip_email_notification\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Account-ID", "<account-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.firstpromoter.com/api/v2/track/sale")
.header("Account-ID", "<account-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\",\n \"event_id\": \"<string>\",\n \"amount\": 123,\n \"uid\": \"<string>\",\n \"quantity\": 123,\n \"plan\": \"<string>\",\n \"currency\": \"<string>\",\n \"mrr\": \"<string>\",\n \"promo_code\": \"<string>\",\n \"billing_country\": \"US\",\n \"tid\": \"<string>\",\n \"ref_id\": \"<string>\",\n \"skip_email_notification\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.firstpromoter.com/api/v2/track/sale")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Account-ID"] = '<account-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"<string>\",\n \"event_id\": \"<string>\",\n \"amount\": 123,\n \"uid\": \"<string>\",\n \"quantity\": 123,\n \"plan\": \"<string>\",\n \"currency\": \"<string>\",\n \"mrr\": \"<string>\",\n \"promo_code\": \"<string>\",\n \"billing_country\": \"US\",\n \"tid\": \"<string>\",\n \"ref_id\": \"<string>\",\n \"skip_email_notification\": true\n}"
response = http.request(request)
puts response.read_body{
"id": 45831949,
"etype": "sale",
"sale_amount": 2000,
"original_sale_amount": 2000,
"original_sale_currency": null,
"event_id": null,
"plan_id": null,
"billing_period": null,
"created_at": "2025-04-25T09:39:42.289Z",
"referral": {
"id": 29203686,
"email": "testme@test1.com",
"uid": null
},
"commissions": [
{
"id": 13533003,
"status": "approved",
"metadata": {},
"is_self_referral": false,
"commission_type": "sale",
"created_by_user_email": null,
"created_by_user_at": null,
"sale_amount": 2000,
"original_sale_amount": 2000,
"original_sale_currency": null,
"event_id": null,
"plan_id": null,
"tier": 1,
"internal_note": null,
"external_note": null,
"unit": "cash",
"fraud_check": "no_suspicion",
"amount": 400,
"is_paid": false,
"is_split": false,
"created_at": "2025-04-25T09:39:42Z",
"status_updated_at": null,
"promoter_campaign": {
"id": 14850130,
"campaign_id": 28004,
"promoter_id": 8262622,
"created_at": "2025-01-16T18:16:41Z",
"promoter": {
"id": 8262622,
"email": "test@promoter.com",
"name": "Test Promoter"
},
"campaign": {
"id": 28004,
"name": "Quinn Ramirez",
"color": "#EC4899"
}
},
"referral": {
"id": 29203686,
"email": "testme@test1.com",
"uid": null
},
"reward": {
"id": 157427,
"name": "20% recurring commission"
}
}
]
}{
"message": "Error. Amount blank or invalid."
}{
"message": "Referral corresponding to email or uid parameter not found or promoter is banned.",
"code": "not_found"
}{
"message": "The 'sale' event with the id 'test_sale_12340987' already exists."
}Tracking Api
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.
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.
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
For other currencies,
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/salePOST
/
sale
cURL
curl --request POST \
--url https://api.firstpromoter.com/api/v2/track/sale \
--header 'Account-ID: <account-id>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>",
"event_id": "<string>",
"amount": 123,
"uid": "<string>",
"quantity": 123,
"plan": "<string>",
"currency": "<string>",
"mrr": "<string>",
"promo_code": "<string>",
"billing_country": "US",
"tid": "<string>",
"ref_id": "<string>",
"skip_email_notification": true
}
'import requests
url = "https://api.firstpromoter.com/api/v2/track/sale"
payload = {
"email": "<string>",
"event_id": "<string>",
"amount": 123,
"uid": "<string>",
"quantity": 123,
"plan": "<string>",
"currency": "<string>",
"mrr": "<string>",
"promo_code": "<string>",
"billing_country": "US",
"tid": "<string>",
"ref_id": "<string>",
"skip_email_notification": True
}
headers = {
"Account-ID": "<account-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Account-ID': '<account-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: '<string>',
event_id: '<string>',
amount: 123,
uid: '<string>',
quantity: 123,
plan: '<string>',
currency: '<string>',
mrr: '<string>',
promo_code: '<string>',
billing_country: 'US',
tid: '<string>',
ref_id: '<string>',
skip_email_notification: true
})
};
fetch('https://api.firstpromoter.com/api/v2/track/sale', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.firstpromoter.com/api/v2/track/sale",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '<string>',
'event_id' => '<string>',
'amount' => 123,
'uid' => '<string>',
'quantity' => 123,
'plan' => '<string>',
'currency' => '<string>',
'mrr' => '<string>',
'promo_code' => '<string>',
'billing_country' => 'US',
'tid' => '<string>',
'ref_id' => '<string>',
'skip_email_notification' => true
]),
CURLOPT_HTTPHEADER => [
"Account-ID: <account-id>",
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.firstpromoter.com/api/v2/track/sale"
payload := strings.NewReader("{\n \"email\": \"<string>\",\n \"event_id\": \"<string>\",\n \"amount\": 123,\n \"uid\": \"<string>\",\n \"quantity\": 123,\n \"plan\": \"<string>\",\n \"currency\": \"<string>\",\n \"mrr\": \"<string>\",\n \"promo_code\": \"<string>\",\n \"billing_country\": \"US\",\n \"tid\": \"<string>\",\n \"ref_id\": \"<string>\",\n \"skip_email_notification\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Account-ID", "<account-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.firstpromoter.com/api/v2/track/sale")
.header("Account-ID", "<account-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\",\n \"event_id\": \"<string>\",\n \"amount\": 123,\n \"uid\": \"<string>\",\n \"quantity\": 123,\n \"plan\": \"<string>\",\n \"currency\": \"<string>\",\n \"mrr\": \"<string>\",\n \"promo_code\": \"<string>\",\n \"billing_country\": \"US\",\n \"tid\": \"<string>\",\n \"ref_id\": \"<string>\",\n \"skip_email_notification\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.firstpromoter.com/api/v2/track/sale")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Account-ID"] = '<account-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"<string>\",\n \"event_id\": \"<string>\",\n \"amount\": 123,\n \"uid\": \"<string>\",\n \"quantity\": 123,\n \"plan\": \"<string>\",\n \"currency\": \"<string>\",\n \"mrr\": \"<string>\",\n \"promo_code\": \"<string>\",\n \"billing_country\": \"US\",\n \"tid\": \"<string>\",\n \"ref_id\": \"<string>\",\n \"skip_email_notification\": true\n}"
response = http.request(request)
puts response.read_body{
"id": 45831949,
"etype": "sale",
"sale_amount": 2000,
"original_sale_amount": 2000,
"original_sale_currency": null,
"event_id": null,
"plan_id": null,
"billing_period": null,
"created_at": "2025-04-25T09:39:42.289Z",
"referral": {
"id": 29203686,
"email": "testme@test1.com",
"uid": null
},
"commissions": [
{
"id": 13533003,
"status": "approved",
"metadata": {},
"is_self_referral": false,
"commission_type": "sale",
"created_by_user_email": null,
"created_by_user_at": null,
"sale_amount": 2000,
"original_sale_amount": 2000,
"original_sale_currency": null,
"event_id": null,
"plan_id": null,
"tier": 1,
"internal_note": null,
"external_note": null,
"unit": "cash",
"fraud_check": "no_suspicion",
"amount": 400,
"is_paid": false,
"is_split": false,
"created_at": "2025-04-25T09:39:42Z",
"status_updated_at": null,
"promoter_campaign": {
"id": 14850130,
"campaign_id": 28004,
"promoter_id": 8262622,
"created_at": "2025-01-16T18:16:41Z",
"promoter": {
"id": 8262622,
"email": "test@promoter.com",
"name": "Test Promoter"
},
"campaign": {
"id": 28004,
"name": "Quinn Ramirez",
"color": "#EC4899"
}
},
"referral": {
"id": 29203686,
"email": "testme@test1.com",
"uid": null
},
"reward": {
"id": 157427,
"name": "20% recurring commission"
}
}
]
}{
"message": "Error. Amount blank or invalid."
}{
"message": "Referral corresponding to email or uid parameter not found or promoter is banned.",
"code": "not_found"
}{
"message": "The 'sale' event with the id 'test_sale_12340987' already exists."
}Authorizations
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
Headers
Account id. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations
Body
application/json
- Option 1
- Option 2
Email of the lead/sign-up. Required if uid is not provided.
Transaction or sale event ID. Required to avoid duplicate sales.
The sale amount in cents. For zero-decimal currencies like JPY, amount should be whole values.
uid of the lead added on signup tracking. Required if email is not provided.
Number of subscriptions/items. Optional if quantity is 1.
Customer plan ID from billing provider. Used for plan-level rewards.
Required only if different from FirstPromoter settings default currency.
Monthly Recurring Revenue generated by the customer.
For promo code tracking.
Customer's billing country as an ISO 3166-1 alpha-2 code (e.g. US). Alpha-3 codes and English country names are also accepted. Unrecognized values are ignored. Shown as the referral and commission country in the dashboard.
Example:
"US"
Visitor tracking ID from _fprom_tid cookie.
Referral ID of the promoter.
Set true to skip email notifications. Default is false.
Response
Sale tracked successfully
Example:
45831949
Example:
"sale"
Example:
2000
Example:
2000
Example:
null
Example:
null
Example:
null
Example:
null
Example:
"2025-04-25T09:39:42.289Z"
Show child attributes
Show child attributes
Show child attributes
Show child attributes