cURL

curl --request POST \
  --url https://firstpromoter.com/api/v1/rewards/create \
  --header 'X-API-KEY: <api-key>'

{
  "id": 123,
  "status": "approved",
  "amount": 123,
  "unit": "cash",
  "created_at": "<string>",
  "lead": "<unknown>",
  "event_id": "<string>",
  "conversion_amount": 123,
  "tier_level": 123,
  "promoter": {
    "id": 123,
    "status": "<string>",
    "cust_id": "<unknown>",
    "email": "<string>",
    "created_at": "<string>",
    "temp_password": "<string>",
    "default_promotion_id": 123,
    "pref": "<string>",
    "default_ref_id": "<string>",
    "note": "<string>",
    "w8_form_url": "<unknown>",
    "w9_form_url": "<unknown>",
    "parent_promoter_id": "<string>",
    "earnings_balance": {},
    "current_balance": {},
    "paid_balance": {},
    "auth_token": "<string>"
  },
  "promotion": {
    "id": 123,
    "status": "<string>",
    "ref_id": "<string>",
    "promo_code": "<string>",
    "customer_promo_code": "<string>",
    "target_reached_at": "<string>",
    "promoter_id": 123,
    "campaign_id": 123,
    "referral_link": "<string>",
    "current_offer": {
      "id": 123,
      "name": "<string>",
      "amount": 123,
      "unit": "<string>",
      "default_promo_code": "<string>"
    },
    "current_referral_reward": {
      "id": 123,
      "amount": 123,
      "unit": "<string>",
      "name": "<string>",
      "per_of_sale": 123,
      "default_promo_code": "<string>"
    },
    "current_promotion_reward": {},
    "current_target_reward": {},
    "campaign_name": "<string>",
    "hidden": true,
    "visitors_count": 123,
    "leads_count": 123,
    "customers_count": 123,
    "refunds_count": 123,
    "cancellations_count": 123,
    "sales_count": 123,
    "sales_total": 123,
    "refunds_total": 123,
    "active_customers_count": 123
  }
}

Rewards

Create new reward

With this endpoint, you can assign a commission generated by a referral, and it will be recorded to the promoter who referred the lead/customer. You can find the referral by lead_id, email, or UID.

If the reward/commission is not generated by a lead/customer, you can assign it directly to a promoter through its promotion. You can find the promotion by promotion_id or ref_id.

Note: To assign rewards/commission for sales via the API use the Tracking API

If this call is successful and you enabled ‘Promoter gets a new commission/reward’ emails for the campaign, it will send emails to the promoter. To skip the emails, set the skip_email_notification parameter to true

HTTP Request
POST https://firstpromoter.com/api/v1/rewards/create

POST

create

cURL

curl --request POST \
  --url https://firstpromoter.com/api/v1/rewards/create \
  --header 'X-API-KEY: <api-key>'

{
  "id": 123,
  "status": "approved",
  "amount": 123,
  "unit": "cash",
  "created_at": "<string>",
  "lead": "<unknown>",
  "event_id": "<string>",
  "conversion_amount": 123,
  "tier_level": 123,
  "promoter": {
    "id": 123,
    "status": "<string>",
    "cust_id": "<unknown>",
    "email": "<string>",
    "created_at": "<string>",
    "temp_password": "<string>",
    "default_promotion_id": 123,
    "pref": "<string>",
    "default_ref_id": "<string>",
    "note": "<string>",
    "w8_form_url": "<unknown>",
    "w9_form_url": "<unknown>",
    "parent_promoter_id": "<string>",
    "earnings_balance": {},
    "current_balance": {},
    "paid_balance": {},
    "auth_token": "<string>"
  },
  "promotion": {
    "id": 123,
    "status": "<string>",
    "ref_id": "<string>",
    "promo_code": "<string>",
    "customer_promo_code": "<string>",
    "target_reached_at": "<string>",
    "promoter_id": 123,
    "campaign_id": 123,
    "referral_link": "<string>",
    "current_offer": {
      "id": 123,
      "name": "<string>",
      "amount": 123,
      "unit": "<string>",
      "default_promo_code": "<string>"
    },
    "current_referral_reward": {
      "id": 123,
      "amount": 123,
      "unit": "<string>",
      "name": "<string>",
      "per_of_sale": 123,
      "default_promo_code": "<string>"
    },
    "current_promotion_reward": {},
    "current_target_reward": {},
    "campaign_name": "<string>",
    "hidden": true,
    "visitors_count": 123,
    "leads_count": 123,
    "customers_count": 123,
    "refunds_count": 123,
    "cancellations_count": 123,
    "sales_count": 123,
    "sales_total": 123,
    "refunds_total": 123,
    "active_customers_count": 123
  }
}

Authorizations

X-API-KEY

string

header

required

Query Parameters

lead_id

string

Lead's id who generated the reward

uid

string

UID of the lead who generated the reward

string

Email of the lead who generated the reward.

promotion_id

string

Promotion id of the promoter who owns the reward

ref_id

string

Promotion referral id of the who owns the reward

reward_type

enum<string>

required

Type of reward

Available options:

cash,

points,

credits,

free_months,

discount_per,

discount_mon

amount

integer

required

Amount of the reward. For reward_type cash(monetary commission) the amount is in cents

status

enum<string>

can be approved(default if this param is omitted), pending or denied

Available options:

approved,

pending,

denied

skip_email_notification

boolean

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

Response

Rewards created response

number

ID of the reward

status

enum<string>

status of the reward.

Available options:

approved,

pending,

denied

amount

integer

amount of the reward. For reward_type cash(monetary commission) the amount is in cents

unit

enum<string>

The reward unit.

Available options:

cash,

credits,

points,

free_months

created_at

string

ISO date string at which the reward is created

lead

any

event_id

string

conversion_amount

integer

tier_level

integer

The reward tier level

promoter

object

Show child attributes

promoter.id

integer

promoter's id

promoter.status

string

promoter's status

promoter.cust_id

any

customer/user ID of the promoter inside your application. This will be included in the webhook event and can be used to identify the promoter in your system if you scribscibe for FirstPromoter's 'promoter_accepted' webhook.

promoter.email

string

Promoter's email

promoter.created_at

string

ISO date string at which the promoter signed up

promoter.temp_password

string

A temporary password the promoter can use to log in to their dashboard if you don't use authentication tokens(auth_token) to sign promoters in automatically.

promoter.default_promotion_id

number

Promoter's default promotion id

promoter.pref

string

Promoter's parent referral id.

promoter.default_ref_id

string

Promoter's default referral id

promoter.note

string

A note/description of promoter

promoter.w8_form_url

any

promoter.w9_form_url

any

promoter.parent_promoter_id

string

parent promoter id

promoter.earnings_balance

object

promoter's earnings balance

promoter.current_balance

object

promoter's current balance

promoter.paid_balance

object

promoter's paid balance

promoter.auth_token

string

authetication token generated when the promoter was created

promotion

object

Show child attributes

promotion.id

number

ID of the promotion.

promotion.status

string

Current offer status.

promotion.ref_id

string

The unique coupon id or coupon code from your billing provider to assign to this affiliate for coupon tracking. This is also known as promo code.

This is discount code/promotion code your customer used or applied on your checkout page. This is also known as display code

promotion.target_reached_at

string

promotion.promoter_id

number

ID of the promoter/affiliate.

promotion.campaign_id

number

ID of the campaign where the promotion runs.

promotion.referral_link

string

Promoter's referral link

promotion.current_offer

object

Show child attributes

promotion.current_offer.id

number

The reward id

promotion.current_offer.name

string

The reward name

promotion.current_offer.amount

number

The reward amount

promotion.current_offer.unit

string

The reward unit (e.g., 'credits', 'free_months', 'cash').

promotion.current_referral_reward

object

Show child attributes

promotion.current_referral_reward.id

number

promotion.current_referral_reward.amount

number

promotion.current_referral_reward.unit

string

promotion.current_referral_reward.name

string

promotion.current_referral_reward.per_of_sale

number

promotion.current_promotion_reward

object

promotion.current_target_reward

object

promotion.campaign_name

string

promotion.hidden

boolean

promotion.visitors_count

number

promotion.leads_count

number

promotion.customers_count

number

promotion.refunds_count

number

promotion.cancellations_count

number

promotion.sales_count

number

promotion.sales_total

number

promotion.refunds_total

number

promotion.active_customers_count

number

Delete a promoter List rewards and commissions

⌘I

API Documentation

Tracking

Leads

Promoters

Rewards

Payouts

Reports

Create new reward

Authorizations

Query Parameters

Response