Skip to main content
POST
cURL
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, it means that the sale is not a referral sale and you’ll get a 204 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.

Authorizations

X-API-KEY
string
header
required

Query Parameters

email
string

required if uid is null

Email of the lead/sign-up

uid
string

required if email is null

uid of the lead added on signup tracking

event_id
string
required

Transaction or sale event ID. It's required to avoid generating duplicate sales in case you mistakenly send the same API call multiple times.

amount
string
required

The sale amount in cents. It's used to calculate commissions/rewards.

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.

quantity
string

Number of subscriptions/items refunded. If it's only one you can skip this parameter.

plan
string

Customer plan ID from the billing provider. It's used to calculate rewards in case you use plan-level rewards feature.

currency
string

This field is only required if the currency of the sale 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.

mrr
string

Sets the Monthly Recurring Revenue generated by the customer. It's used only for calculating the MRR generated by the program, not for calculating the commissions.

promo_code
string

For promo code/coupon code tracking. If you gave a unique coupon to a promoter and you added it on his promotion, you can pass it here and it will CREATE a new lead and a sale for that promoter (if it doesn't exist already).

billing_country
string

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.

tid
string

You can avoid a signup tracking call by providing the _fprom_tid cookie value (visitor tracking id) read on your system

ref_id
string

You can avoid signup tracking call by providing the ref_id(referral id) of the promoter

skip_email_notification
boolean

Set this to true to skip email notifications. Default is false.

created_at
string<date-time>

ISO 8601 date string of when the sale occurred. Defaults to now.

subscription_id
string

Subscription ID from your billing provider. Stored in the lead metadata.

start_recurring_reward_in
integer

Number of days to delay the first commission. The sale will be scheduled and tracked at now + start_recurring_reward_in days.

recurring_reward_frequency
integer

Interval in days between recurring commission events. Used together with start_recurring_reward_in.

max_recurring
integer

Maximum number of recurring commission events to generate. Requires recurring_reward_frequency to be set.

ecom_sale
boolean

Set to true for e-commerce one-time sales (non-subscription).

Response

Sale tracked successfully

id
integer
Example:

33847194

type
string
Example:

"sale"

amount_cents
integer
Example:

1000

reward
object
lead
object
promoter
object