Referrals are records of when a user signs up to your app after visiting a referral link.
Once a referred user signs up to a paid plan, this is considered a "conversion". Creation and conversion are the two main events in a referral's life and the API lets you handle both programmatically from your app.
List referrals
GET https://api.refermo.co/v1/referrals/
Request parameters
None.
Response values
Pagination
count
(int)
Total results for this query (including other pages of results).next
(string)
The URL for the next page of results, ornull
if there isn't one.previous
(string)
The URL for the previous page of results, ornull
if there isn't one.
Referral data
id
(string, 32 chars)
The unique Refermo ID for this referral.member_id
(string, 32 chars)
The unique Refermo ID for the referring member.user_identifier
(string)
The unique ID for the referred user from your app.created_at
(unix timestamp)converted_at
(unix timestamp ornull
if referral has not converted)is_converted
(boolean)
A simple boolean to see if the referral has converted.coupon_code
(string ornull
)
The discount code created if this referral has double-sided rewards. This coupon can be applied at checkout to give the referred user a discount, based on your campaign settings.subscription
(dictionary ornull
)
If this referral has converted, it will have been assigned the subscription which was created as it was converted. This dictionary has the same values as in the Subscription endpoint.source
(string, optionsapp
,api
orjs
)
This tells how the referral was created.campaign_id
(string, 8 chars)
The unique ID for the campaign this referral was created within.reward_type
(string, optionscredit
orcommission
)
The type of reward created for this referral.reward_amount
(decimal as a string)
The amount of each reward created for this referral.reward_threshold
(decimal as a string)
The amount the referred user needs to be spend before rewards are created.currency
(string, 3 chars)
The 3-character currency code used for this referral's rewards. This was copied from the referral's campaign when it was created.stats
(dictionary)
Numerical stats for this referral.rewards_completed
(boolean)
This shows if the referral will receive future rewards or not. For example, credit-based referrals will only have one reward, whereas a recurring commission-based referral will get ongoing rewards.rewards
(list)
A list of rewards which have been created for this referral. This is a list of objects with id, reward type, amount rewarded, currency of the reward amount, the timestamp when the reward was created and the ID of the subscription payment in Paddle which triggered the reward.
Example response
HTTP 200 OK
{
"count": 18,
"next": null,
"previous": null,
"results": [
{
"id": "4b8024de11341839cf6cdafbd1dfaa01",
"member_id": "c235f4c1f987260699843afeb59b3e16",
"user_identifier": "dancustomer@gmail.com",
"created_at": 1637123678,
"converted_at": 1637123821,
"is_converted": true,
"coupon_code": "31A30BAF",
"subscription": {
"id": 9682864,
"unit_price": "19.00",
"currency": "USD",
"status": "active",
"email": "dancustomer@gmail.com",
"next_bill_date": "2022-01-05",
"last_bill_date": "2021-11-05",
"plan": {
"id": 665966,
"name": "Monthly",
"amount": "19.00",
"currency": "USD",
"interval": "month",
"frequency": 1
}
},
"source": "js",
"campaign_id": "4d0e29b3",
"reward_type": "credit",
"reward_amount": "10.00",
"reward_threshold": "0.00",
"currency": "USD",
"stats": {
"rewards": 1,
"credit_earned": "10.00",
"commission_earned": "0.00",
"currency": "USD"
},
"rewards_completed": true,
"rewards": [
{
"id": "eeaa35bb13a70bc6834f35297ee74779",
"type": "credit",
"amount": "10.00",
"currency": "USD",
"created_at": 1638702715,
"payment_id": 32259282
}
]
},
...
]
}
Filters
List referrals by a specific member
To get a list referrals by one of your members, use the query parameter member
and provide the id
of the member, like this:
GET https://api.refermo.co/v1/referrals/?member=a7ea424c3cb5e7dcdfadf3b45abc6f4e
Retrieve a referral
GET https://api.refermo.co/v1/referrals/[id]/
Request parameters
id
The referral's Refermo ID.
Response values
id
(string, 32 chars)
The unique Refermo ID for this referral.member_id
(string, 32 chars)
The unique Refermo ID for the referring member.user_identifier
(string)
The unique ID for the referred user from your app.created_at
(unix timestamp)converted_at
(unix timestamp ornull
if referral has not converted)is_converted
(boolean)
A simple boolean to see if the referral has converted.coupon_code
(string ornull
)
The discount code created if this referral has double-sided rewards. This coupon can be applied at checkout to give the referred user a discount, based on your campaign settings.subscription
(dictionary ornull
)
If this referral has converted, it will have been assigned the subscription which was created as it was converted. This dictionary has the same values as in the Subscription endpoint.source
(string, optionsapp
,api
orjs
)
This tells how the referral was created.campaign_id
(string, 8 chars)
The unique ID for the campaign this referral was created within.reward_type
(string, optionscredit
orcommission
)
The type of reward created for this referral.reward_amount
(decimal as a string)
The amount of each reward created for this referral.reward_threshold
(decimal as a string)
The amount the referred user needs to be spend before rewards are created.currency
(string, 3 chars)
The 3-character currency code used for this referral's rewards. This was copied from the referral's campaign when it was created.stats
(dictionary)
Numerical stats for this referral.rewards_completed
(boolean)
This shows if the referral will receive future rewards or not. For example, credit-based referrals will only have one reward, whereas a recurring commission-based referral will get ongoing rewards.rewards
(list)
A list of rewards which have been created for this referral. This is a list of objects with id, reward type, amount rewarded, currency of the reward amount, the timestamp when the reward was created and the ID of the subscription payment in Paddle which triggered the reward.
Example response
HTTP 200 OK
{
"id": "4b8024de11341839cf6cdafbd1dfaa01",
"member_id": "c235f4c1f987260699843afeb59b3e16",
"user_identifier": "dancustomer@gmail.com",
"created_at": 1637123678,
"converted_at": 1637123821,
"is_converted": true,
"coupon_code": "31A30BAF",
"subscription": {
"id": 9682864,
"unit_price": "19.00",
"currency": "USD",
"status": "active",
"email": "dancustomer@gmail.com",
"next_bill_date": "2022-01-05",
"last_bill_date": "2021-11-05",
"plan": {
"id": 665966,
"name": "Monthly",
"amount": "19.00",
"currency": "USD",
"interval": "month",
"frequency": 1
}
},
"source": "js",
"campaign_id": "4d0e29b3",
"reward_type": "credit",
"reward_amount": "10.00",
"reward_threshold": "0.00",
"currency": "USD",
"stats": {
"rewards": 1,
"credit_earned": "10.00",
"commission_earned": "0.00",
"currency": "USD"
},
"rewards_completed": true,
"rewards": [
{
"id": "eeaa35bb13a70bc6834f35297ee74779",
"type": "credit",
"amount": "10.00",
"currency": "USD",
"created_at": 1638702715,
"payment_id": 32259282
}
]
}
Errors
If a member cannot be found, the endpoint will return a HTTP 404
response with an error message.
HTTP 404 Not Found
{
"detail": "Not found."
}
Retrieve a referral by user identifier
You may want to get details of a referral for one of your app's users, rather than by an ID.
In this case, use the /v1/referrals/user/[user_identifier]/
endpoint.
The response data and errors are exactly the same as the standard /v1/referrals/[id]/
endpoint.
Create a referral
POST https://api.refermo.co/v1/referrals/
Creating a referral in essence means recording a new sign up that has occured after someone has visited a referral link.
The easiest way to record referrals is with the Javascript API, but you can also create them with this API.
Note: If you call this endpoint with the exact same data, the existing matching referral will be returned; the system will never create duplicate referrals for a pair of user identifier and member code.
Request parameters
- None
Request values
user_identifier
(string) required
A unique identifier for this user in your app. It could be a user ID, username or email address. This value should be something that never changes in your app.member_code
(string) required
The referring member's referral code. This is the same code from your referral links (yourdomain.com/?via=CODE
) so you need to have access to this somehow when you create a referral.
When using the Javascript API, this code is stored—and can therefore be accessed—in the browser as a cookie calledrefermo-ref
.
Example request
POST
{
"user_identifier": "dan@gmail.com",
"member_code": "4QE39VDA"
}
Response values
id
(string, 32 chars)
The unique Refermo ID for this referral.member_id
(string, 32 chars)
The unique Refermo ID for the referring member.user_identifier
(string)
The unique ID for the referred user from your app.created_at
(unix timestamp)converted_at
(unix timestamp ornull
if referral has not converted)
This will always benull
for brand new referrals.is_converted
(boolean)
A simple boolean to see if the referral has converted.coupon_code
(string ornull
)
The discount code created if this referral has double-sided rewards. This coupon can be applied at checkout to give the referred user a discount, based on your campaign settings, so you can save this locally and display it when this referred user checks out.subscription
(dictionary ornull
)
If this referral has converted, it will have been assigned the subscription which was created as it was converted. This dictionary has the same values as in the Subscription endpoint.source
(string, optionsapp
,api
orjs
)
This tells how the referral was created.campaign_id
(string, 8 chars)
The unique ID for the campaign this referral was created within.reward_type
(string, optionscredit
orcommission
)
The type of reward created for this referral.reward_amount
(decimal as a string)
The amount of each reward created for this referral.reward_threshold
(decimal as a string)
The amount the referred user needs to be spend before rewards are created.currency
(string, 3 chars)
The 3-character currency code used for this referral's rewards. This was copied from the referral's campaign when it was created.stats
(dictionary)
Numerical stats for this referral.rewards_completed
(boolean)
This shows if the referral will receive future rewards or not.rewards
(list)
A list of rewards which have been created for this referral. This will be empty for brand new referrals.
Example response
HTTP 200 OK
{
"id": "7e762faceb019337db56c408b54798bd",
"member_id": "44dc4d920bcfe2d3183ae33bc0f9b4ed",
"user_identifier": "testingapi@gmail.com",
"created_at": 1641215449,
"converted_at": null,
"is_converted": false,
"discount_code": null,
"subscription": null,
"source": "api",
"campaign_id": "1ba89be6",
"reward_type": "credit",
"reward_amount": "10.00",
"reward_threshold": "0.00",
"currency": "USD",
"stats": {
"rewards": 0,
"credit_earned": "0.00",
"commission_earned": "0.00",
"currency": "USD"
},
"rewards_completed": false,
"rewards": []
}
Errors
If you forget to include one of the two required values, you will get a HTTP 400
response.
HTTP 400 Bad Request
{
"user_identifier": [
"This field is required."
]
}
You'll also get an error response if a member cannot be found with the provided referral code.
HTTP 400 Bad Request
{
"member_code": [
"Member with code WRONGCODE was not found."
]
}
Update a referral
This endpoint is not available. Once created, referrals cannot be edited.
To record a referral conversion, use the conversion endpoint below.
Record a conversion
POST https://api.refermo.co/referrals/[id]/conversion/
Once a referral has been created (a new user signed up via a referral link), you need to tell Refermo when the user "converts" (when they start a paid subscription). This action triggers rewards for your referrers.
You need to provide either a checkout_id
or subscription_id
for each conversion, both of which are values from Paddle. This ties the conversion to a Paddle subscription, which allows Refermo to create referral rewards.
Request parameters
id
The referral's ID returned fromRefermo.signup()
or the API.
Request values
checkout_id
(string, max 100 chars) required ifsubscription_id
is not provided
The subscription's checkout ID. You can get this from Paddle's webhooks or checkout event data.subscription_id
(string) required ifcheckout_id
is not provided
The subscription's numerical ID from Paddle. You can get this from Paddle's webhooks, checkout event data or the API.
Example request
POST
{
"checkout_id": "110012887-chre607875daf76-a4bac0859a",
}
Delete a referral
DELETE https://api.refermo.co/v1/referrals/[id]/
Request parameters
id
The referral's ID returned fromRefermo.signup()
or the API.
Response values
None.
Example response
HTTP 204 No Content