Introduction

This technical documentation details how to get your Buyapowa refer-a-friend campaign up and running on your website.

A typical integration involves embedding the refer-a-friend campaign on a page of your website as well as adding the Buyapowa tracking script where conversion occurs.

These two steps cover the basic technical integration for your refer-a-friend campaign. The Buyapowa platform contains a wealth of advanced features which may be recommended by your client services manager.

Embedding

Embed your campaign

Your refer-a-friend campaign lives on one of your web pages. Using the Buyapowa client library, you will embed on this page the refer-a-friend campaign powered by Buyapowa.

Cookie subdomain

Buyapowa uses cookies, which will need to be set on your behalf. In order to satisfy browsers that the Buyapowa programme is an integral part of your website, we need a ‘cookie subdomain’. This will ensure that cookies written by the Buyapowa platform are kept in place as would any other cookie from your website. To do this, you will need to take the following steps:

  • Choose a subdomain, which must be on the same domain where you will be embedding the Buyapowa content, and let us know what it is. For example: bp.your-website.com.
  • We will provide you with two DNS CNAME records you must set on your domain to support the cookie domain.
  • Once this is done, you will be ready to embed your Buyapowa programme.

Integration

Load the Buyapowa library by adding the following in the <head>:

<script src="//cdn.co-buying.com/embedding.min.js"></script>
<meta property="og:url" content="https://{{market_domain}}/iaf/{{campaign_slug}}/og"/>

Add this HTML container in the <body> to host the refer-a-friend component:

<div id="bp_error" style="display: none;">Sorry, something went wrong</div>
<div id="bp_div"></div>

Finally, add the embed script:

<script type="text/javascript">
  var buyapowa = new Buyapowa({url: "https://{{market_domain}}", market: "{{market}}"}, "bp_div", "bp_error");
  buyapowa.embedReferAFriend({
    "campaign": "{{campaign_slug}}",
    "locale": "{{locale}}"
  });
</script>
Variable Value
{{market_domain}} This is your cookie subdomain, if you have set one up. For example: bp.your-website.com. If you have not set one up, a value will be provided by your client services manager on the buyapowa.com or buyapowa.net domain.
{{market}} Value to be provided by your client services manager.
{{campaign_slug}} Value to be provided by your client services manager.

Although there’s no minimum height or width requirement for the #bp_div, we recommend:

  • a minimum height of 800px
  • a minimum width of 871px on desktop view
  • a width of 100% of the screen without any margin or padding on mobile view

Your campaign might not display correctly if you do not follow these recommendations.

List of parameters:

Parameter Format Example
locale
string
The locale of the user visiting your site. If one is not provided, it will use the default for the market en

Add Buyapowa unavailable screen - optional

The Buyapowa embed tag can optionally take the id of an additional <div> element on your page as a third parameter, e.g. <div id="bp_error"></div>

You should set this element’s display property to none, eg. display: none;

This element will be shown should the embed request fail.

The content and copy of the <div> are controlled by you and can contain any kind of error message.

Restrict access to the campaign

It may make sense for your particular setup to restrict your refer-a-friend campaign to a subset of customers only.

We offer different solutions to restrict who can participate in the campaign and refer their friends and the recommended way to do this is to embed your campaign on a page that requires authentication.

… to authenticated customers

It may make sense for your particular setup to restrict your refer-a-friend campaign to your authenticated customers only.

Integration

You would need to make sure that only customers who are authenticated can access the page where you have embedded the campaign.

If you are using the Buyapowa friend landing page then you would need to make sure that friends can access the campaign even though they are not authenticated on your website:

  • either by making sure that the page where the campaign is embedded is accessible to users who are not authenticated when our systems adds bp_l=false as part of the query string to your refer-a-friend page URL. If this is included, you should not require authentication.
  • or by embedding the campaign a second time on a separate page which doesn’t require authentication (please see Embed your campaign)

Seamless signup & login feature - optional

You will need to enable this feature in your market settings, and also pass these additional parameters in your embedding code:

Name Value
auto
boolean
Should be set to true for automatic login
name
string
Full name of the authenticated customer, in the format of FirstName LastName
email
string
Email address of the authenticated customer
custom_field
string
If your refer-a-friend campaign is set up to accept a custom field, the value of the custom field for the authenticated customer.
marketing_opt_in
string
Marketing preferences of the authenticated customer, the value should be true or false. If omitted, it defaults to false.
locale
string
The locale of the user visiting your site. If one is not provided, it will use the default for the market
signed_keys
string
A string containing a comma delimited list of the keys which you will be signing against, this should include name and email as a minimum.
signature
string
Signature of the signed fields

For example, if John Doe whose email address is john@doe.com was authenticated on your website, your embedding code might look as follows:

<script src="//cdn.co-buying.com/embedding.min.js"></script>
<div id="bp_error" style="display: none;">Sorry, something went wrong</div>
<div id="bp_div"></div>
<script type="text/javascript">
  var buyapowa = new Buyapowa({url: "https://{{market_domain}}", market: "{{market}}"}, "bp_div", "bp_error");
  buyapowa.embedReferAFriend({
    "campaign": "{{campaign_slug}}",
    "auto": true,
    "name": "John Doe",
    "email": "john@doe.com",
    "marketing_opt_in": "true",
    "locale": "en",
    "signed_keys": "name, email",
    "signature": "e8ca91ebc4b1d0831086f1d93ce76b9f15fbebf23883dcbf1361194752befb22"
  });
</script>

When you choose to restrict the access to your refer-a-friend campaign to your authenticated customers you can seamlessly sign up and log these users into your refer-a-friend campaign by including additional parameters on the embed code.

This means that as customers authenticated through your own website, they don’t have to go through another sign-up or login form to use the refer-a-friend campaign.

You will have to calculate the signature value by generating a SHA256 hash from a JSON object that should include the signed keys appearing in alphabetical order and their values along with your Buyapowa account’s secret key.

{"email":"{{customer_email_address}}","name":"{{customer_full_name}}","secret":"{{secret_key}}"}

For example, if my account’s secret key is afd46269f68a4b63b6a926d8bad9f5b5 and given the embedding code for John Doe whose email address is john@doe.com, I would take this string:

{"email":"john@doe.com","name":"John Doe","secret":"afd46269f68a4b63b6a926d8bad9f5b5"}

and generate a SHA256 hash of this string to use as the signature:

e8ca91ebc4b1d0831086f1d93ce76b9f15fbebf23883dcbf1361194752befb22

… using other solutions

If you would like to restrict the access to your campaign but embedding on a page that requires authentication is not an option, you would be able to restrict access by prompting your customers for additional information when signing up to the campaign.

You can then choose to verify this additional piece of information before allowing a user to sign up with the Customer segmentation API.

Tracking referral conversions

Tracking tag

Edit the <head> section of your conversion page to add the following:

<script src="//cdn.co-buying.com/embedding.min.js"></script>

Edit the <body> section of the same page & add the following before the </body> end tag:

<script type="text/javascript">
  var buyapowa = new Buyapowa({url: "https://{{market_domain}}", market: "{{market}}"});
  buyapowa.track({
    "customer_name": "<first_name>, <last_name>",
    "customer_email": "<email_address>",
    "marketing_opt_in": "<true_or_false>",
    "order_number": "<unique_identifier>",
    "order_value": "<order_value>",
    "reward_category": "<reward_category>", //only required for intelligent rewards
    "voucher_code": "<voucher_code>",
    "signed_keys": "<signed_keys>", //only if you want to sign the requests
    "signature": "<signature>", //only if you want to sign the requests
    "locale": "<locale>"
  });
</script>

Referral conversions will be tracked by adding tracking code to the page where your customers transact.

It could be on a checkout confirmation page, a registration confirmation page or some other page defined by you.

Variable Value
{{market_domain}} This is your cookie subdomain, if you have set one up. For example: bp.your-website.com. If you have not set one up, a value will be provided by your client services manager on the buyapowa.com or buyapowa.net domain.

In the tracking code, all <values> will need to be replaced with your own variables returning the expected values.

List of parameters:

Parameter Format Example
customer_name
string
FirstName, LastName John, Doe
customer_email
string
Standard email address format john@doe.com
marketing_opt_in
string
Whether the customer has opted into marketing emails, true or false true
  • If omitted, the value defaults to false
  • If the customer has indicated their preference while on the ‘friend landing page’, the value remains unchanged from the value submitted previously on the ‘friend landing page’
  • If you choose to promote your refer-a-friend campaign with our auto-invite emails, we will never send auto-invite emails to customers for whom we received the value false
order_number
string
any unique identifier you use to identify this conversion ORDER123
order_value
string
No currency symbol; format as XX.YY 12.89
reward_category
string
The reward category setting the type of reward both parties are eligible to - only required for intelligent rewards 25OFF
voucher_code
string
The code used at checkout BPCRAW1234

If you accept multiple vouchers in your checkout, you can pass all the voucher codes to us and we’ll automatically detect the ones relevant for Buyapowa tracking.

Instead of voucher_code above, please send voucher_codes with all the voucher codes redeemed in an array:

“voucher_codes”: [“CODE1”, “CODE2”]
array

signed_keys
string
A string containing a comma delimited list of the keys which you will be signing against, this should include order_number and customer_email as a minimum. If you are using intelligent rewards then this should also include reward_category
signature
string
Signature of the signed keys - only if you have chosen to sign the requests
locale
string
The locale of the customer. When a customer receives any emails related to the referral campaign, it will be displayed in the locale provided here. If one is not provided, it will use the default for the market en

Sign the tracking requests - optional

We strongly recommend that you sign the request to ensure that tracking requests are originating from your website, and are not forged by customers to increase their referrals, you can choose this optional feature that requires all tracking requests to be signed using a secret key that only you and Buyapowa know. This ensures that no modifications can be made to the tracking request.

Variable Value
{{secret_key}} value to be provided by your client services manager

You will have to calculate the signature value by generating a SHA256 hash from a JSON object that should include the signed keys appearing in alphabetical order and their values along with your Buyapowa account’s secret key.

{"customer_email":"{{customer_email_address}}","order_number":"{{order_number}}","secret":"{{secret_key}}"}

For example, if my account’s secret key is afd46269f68a4b63b6a926d8bad9f5b5 and given the tracking request is for John Doe’s order whose email address is john@doe.com and the order number is ORDER123, I would take this string:

{"customer_email":"john@doe.com","order_number":"ORDER123","secret":"afd46269f68a4b63b6a926d8bad9f5b5"}

and generate a SHA256 hash of this string to use as the signature:

351381bad6a8c4c3ca0baff383bf64b5248e6ba467314b88c84e3d5e9c91da33

Pass this in as the value of the signature in the tracking script and we will do the same process on our server. If the signature does not match, the tracking request will not be processed.

Troubleshooting and errors

Go to your browser’s inspector Network tab (cmd+alt+i / ctrl+shift+c), when you reach the conversion page you should look for a request to track.co-buying.com, and check the status code:

Code Scenario
200 - 201 Your request was understood and successful.

If you can’t find any the request or if you find it but get a different status code or a JavaScript error then there is a problem with your integration, please review the above instructions.

This article can help you debug your integration: My debugging toolkit

Referral tracking API

If you are not using our tracking code on the page where your customers transact to track referral conversions, you can use our API to track the conversions instead.

You can send us either a batch of conversion data or a single conversion at a time.

▶ Tracking - Batch upload

The request should be made as a POST like the following example:

curl -X POST -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" -H "Content-Type: multipart/form-data;" -F "csv=@{{file.csv}}" 'https://api.co-buying.com/api/referrals/track'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the content in a csv file:

ReferrerEmail,VoucherCode,FullName,EmailAddress,MarketingOptIn,OrderValue,OrderNumber,OrderTimestamp,RewardCategory,ClientData_membership_number,Locale
,BPCODE1234,"Jane, Smith",jane@smith.com,true,12.89,ORDER123,1321009871,25OFF,662-56-3593,en
john@doe.com,,"Dan, Smith",dan@smith.com,false,45.99,ORDER124,1321009892,50OFF,662-57-3241,pt
Variable Value
{{file.csv}} To be replaced by a path to your csv file

Send us each batch of conversion data in a CSV. The CSV should have headings on the relevant columns as follows:

Parameter Description Example
ReferrerEmail The email address of the referrer john@doe.com
VoucherCode The code used at checkout BPCRAW1234
FullName The full name of the customer as FirstName, LastName “Jane, Smith”
EmailAddress The email address of the customer jane@smith.com
MarketingOptIn Whether the customer has opted into marketing emails, true or false. If omitted, the value defaults to false. true
OrderValue No currency symbol; format as XX.YY 12.89
OrderNumber any unique identifier you use to identify this conversion ORDER123
OrderTimestamp When the conversion was created, as a UNIX timestamp - the number of seconds since 1970-01-01 00:00:00 UTC 1321009871
RewardCategory The reward category setting the type of reward both parties are eligible to - only required for intelligent rewards 25OFF
ClientData_{{key}} Extra client specified metadata associated with the customer checking out eg. ClientData_membership_number 662-56-3593
Locale The locale of the customer. When a customer receives any emails related to the referral campaign, it will be displayed in the locale provided here. If one is not provided, it will use the default for the market en

▶ Tracking - Single upload

The request should be made as a POST like the following example:

curl -X POST -H 'auth_id: {{market_id}}' -H 'auth_token: {{auth_token}}' -H 'content-type: application/json' -d '{{json_object}}' 'https://api.co-buying.com/api/referrals/track'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the JSON object:

{
  "order" : {
    "referrer_email" : "john@doe.com",
    "voucher_code" : "BPCRAW1234",
    "full_name" : "Jane, Smith",
    "email_address" : "jane@smith.com",
    "marketing_opt_in" : "true",
    "order_value" : "12.89",
    "order_number" : "ORDER12345678",
    "order_timestamp" : "1321009871",
    "reward_category": "25OFF",
    "client_data": {
      "membership_number": "662-56-3593"
    },
    "locale": "en"
  }
}
Variable Value
{{json_object}} To be replaced by the json object itself

To send us a single conversion, you will need to send the details as a JSON object. The JSON should be formatted as follows:

Parameter Description Example
referrer_email
string
The email address of the referrer john@doe.com
voucher_code
string
The code used at checkout BPCRAW1234
full_name
string
The full name of the customer as FirstName, LastName Jane, Smith
email_address
string
The email address of the customer jane@smith.com
marketing_opt_in
string
Whether the customer has opted into marketing emails, true or false. If omitted, the value defaults to false. true
order_value
string
No currency symbol; format as XX.YY 12.89
order_number
string
Any unique identifier you use to identify this conversion ORDER123
order_timestamp
string
When the conversion was created, as a UNIX timestamp - the number of seconds since 1970-01-01 00:00:00 UTC 1321009871
reward_category
string
The reward category setting the type of reward both parties are eligible to - only required for intelligent rewards 25OFF
client_data
json
Extra client specified metadata associated with the customer checking out { “membership_number”: “662-56-3593” }
locale
string
The locale of the customer. When a customer receives any emails related to the referral campaign, it will be displayed in the locale provided here. If one is not provided, it will use the default for the market en

Referral tracking Interface

If you are unable to integrate with our Referral tracking API, we have an interface ready for your team to use on a regular basis to report referral conversions.

  1. Create a CSV matching the format described on the interface
  2. Select your csv file
  3. Upload it by clicking the button Track orders

Referral reconciliation

You can ensure that rewards are only distributed when a successful referral has been made. This can involve holding back the distribution of rewards.

Example: You can confirm a referral is successful when a payment has gone through, or you might want to invalidate the referral if the purchase is cancelled or returned.

By switching on the referral reconciliation feature, every time we will track a referral conversion, we will set it to a “pending confirmation” status, until you run the reconciliation process.

Referral reconciliation API

Our API allows you to reconcile referrals.

You can send us either a batch of referral reconciliation data or a single referral reconciliation at a time to update the status of referrals.

▶ Reconciliation - Batch upload

The request should be made as a POST like the following example:

curl -X POST -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" -H "Content-Type: multipart/form-data;" -F "csv=@{{file.csv}}" 'https://api.co-buying.com/api/referrals/confirmations'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the content in a csv file:

OrderNumber,Status,RewardCategory
ORDER123,confirmed,25OFF
ORDER928,failed,
Variable Value
{{file.csv}} To be replaced by a path to your csv file

To send us a batch of referrals to reconcile, you will need to send the details in a CSV. The CSV should have headings on the relevant columns as follows:

Header Format Example
OrderNumber The identifier you are passing when tracking the referral ORDER928
Status The status should be one of the valid statuses listed below confirmed
RewardCategory The reward category setting the type of reward both parties are eligible to - only required for intelligent rewards 25OFF

▶ Reconciliation - Single upload

The request should be made as a POST like the following example:

curl -X POST -H 'auth_id: {{market_id}}' -H 'auth_token: {{auth_token}}' -H 'content-type: application/json' -d '{{json_object}}' 'https://api.co-buying.com/api/referrals/confirmations'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the JSON object:

{
  "order" : {
    "order_number" : "ORDER928",
    "status" : "confirmed",
    "reward_category" : "25OFF"
  }
}
Variable Value
{{json_object}} To be replaced by the json object itself

To send us a single referral to reconcile, you will need to send the details as a JSON object. The JSON should be formatted as follows:

Parameter Format Example
order_number
string
The identifier you are passing when tracking the referral ORDER928
status
string
The status should be one of the valid statuses listed below confirmed
reward_category
string
The reward category setting the type of reward both parties are eligible to - only required for intelligent rewards 25OFF


▶ List of all valid statuses

Value Description
confirmed Will issue a successful referral and trigger any related customer events
(e.g. emailing the customer)
failed Will set a referral to failed
manual‑pass Will issue a successful referral but NOT trigger any related customer events
(e.g. emailing the customer)
restore Will set a cancelled referral to pending

Referral reconciliation Interface

If you are unable to integrate with our Referral reconciliation API, we have an interface ready for your team to use on a regular basis.

  1. Download the list of all referrals which are pending your verification using the interface
  2. Update the status column the file with the relevant status for each referrals
  3. Upload the file with the statuses updated using the interface

Customer sign up

The standard way for your customers to sign up to your refer-a-friend campaign is by filling in a simple form with their name and email address (optionally a third form field can be added to collect an additional piece of data).

To log back into the campaign in the future, they can simply follow the unique return URL on the welcome email or any other refer-a-friend related email sent from the platform.

Signups API

Creating signups enables you to generate:

  • share links for your customers without having them sign up or log in to your refer-a-friend campaign first
  • dashboard links to allow each of these customers to access their refer-a-friend dashboard and take advantage of all available sharing tools

You can send us either a batch of signup data or a single signup at a time to generate these types of links.

▶ Signups - Batch upload

The request should be made as a POST like the following example:

curl -X POST -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" -H "Content-Type: multipart/form-data;" -F "campaign_slug={{campaign_slug}}" -F "csv=@{{file.csv}}" -F "send_auto_invite_emails={{send_auto_invite_emails}}" 'https://api.co-buying.com/api/signups/upload'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the content in a csv file:

Email,FirstName,LastName,CustomField,ClientData_customer_id,Locale
jane@smith.com,Jane,Smith,07123456789,552-56-3593,en
john@doe.com,John,Doe,07987654321,662-56-3593,fr

Expected response:

Code Scenario
303 Your request was understood. A URL is returned both in the location header and in the JSON response body. That URL is where you can download an updated CSV containing the generated share/dashboard URLs.

URL format: {"url": "http://api.co-buying.com/api/signups/download/<uuid>"}

Expected response when you try to access the url you were given:

Code Scenario
202 Your request was understood. The share/dashboard links are being generated.
200 Your request was successful and the share/dashboard links have been generated as a result you should get the CSV updated
Variable Value
{{campaign_slug}} value to be provided by your client services manager
{{file.csv}} To be replaced by a path to your csv file
{{send_auto_invite_emails}} When true, will send invitation emails to any new users

You will need to upload a CSV containing details of the customers for whom you’d like to generate these links.

The CSV should have headings on the relevant columns as follows:

Header Description Example
Email The customer’s first email address jane@smith.com
FirstName The customer’s first name Jane
LastName The customer’s last name (optional) Smith
CustomField If you are using a custom field to identify a customer, then this field may contain content such as a membership ID, or phone number 07123456789
ClientData_{{key}} Extra client specified metadata associated with the referrer signed up to the campaign eg. ClientData_customer_id 662-56-3593
Locale The locale of the customer. When a customer receives any emails related to the referral campaign, it will be displayed in the locale provided here. If one is not provided, it will use the default for the market en

You will receive an updated CSV containing the following additional columns:

Header Description
ShareURL Each customer’s unique share link
DashboardURL Each customer’s link to their dashboard

▶ Signups - Single upload

The request should be made as a POST like the following example:

curl -X POST -H 'auth_id: {{market_id}}' -H 'auth_token: {{auth_token}}' -H 'content-type: application/json' -d '{{json_object}}' 'https://api.co-buying.com/api/signups'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the JSON request object:

{
  "campaign_slug" : "{{campaign_slug}}",
  "send_auto_invite_email": true,
  "signup" : {
    "email" : "jane@smith.com",
    "first_name" : "Jane",
    "last_name" : "Smith",
    "custom_field_value" : "07123456789",
    "client_data": {
      "client_id": "662-56-3593"
    },
    "locale": "en"
  }
}

Example of the JSON response object:

{
  "share_url" : "https://example.com/share_path",
  "dashboard_url" : "https://example.com/dashboard_path"
}
Variable Value
{{json_object}} To be replaced by the json object itself

To send us a single signup to create, you will need to send the details as a JSON object. The JSON should be formatted as follows:

Parameter Description Example
{{campaign_slug}}
string
A value to be provided by your client services manager
send_auto_invite_email
boolean
If the user is new, we’ll send them an invitation email
email
string
The customer’s first email address jane@smith.com
first_name
string
The customer’s first name Jane
last_name
string
The customer’s last name Smith
custom_field_value
string
If you are using a custom field to identify a customer, then this field may contain content such as a membership ID, or phone number 07123456789
client_data
json
Extra client specified metadata associated with the referrer signed up to the campaign { “customer_id”: “662-56-3593” }
locale
string
The locale of the customer. When a customer receives any emails related to the referral campaign, it will be displayed in the locale provided here. If one is not provided, it will use the default for the market en

You will receive a JSON response containing the following details:

Parameter Description
share_url The customer’s unique share link
dashboard_url The customer’s link to their dashboard


Auto Sign-ups

Creating one-off auto sign-up URL is a lightweight method to help customers through your refer-a-friend campaign’s sign-up process.

This will allow you to send single-click URLs to customers which they can use to get signed up without having to fill in the sign up form. In order to do this; you will need to pass the customer details inside these single-click URLs.

▶ Encrypted sign-up URLs

For example If your refer a friend landing page lives on: www.company.com/refer-a-friend

https://www.mycompany.com/refer-a-friend

To create an encrypted one-off auto sign up URL for a user whose first name is John and last name is Doe and has the email address john@doe.com You will need to first create the following JSON Object:

{"email":"john@doe.com","name":"John Doe","auto":"true"}

You then need to encrypt this JSON Object using your {{auth_token}}. For this example the {{auth_token}} is

fd7cf959-8a3d-431e-975b-b5d3f36aa710

You need to encrypt the object with the first 32 values of this token, which is:

fd7cf959-8a3d-431e-975b-b5d3f36a

Once the JSON object is encrypted and base64 encoded, it will look like the following:

xXqWA+4gNXzWJ+RdmPRylfonBLMkpHtAM3ybYHpm7t6YPRCLQvyYwVKoyC9nQic4y3YPTWWICC0p1pEG995WgQ==

You should then add this encoded string as the value of a query string parameter called bp_e. The final URL for this example would look like this:

www.company.com/refer-a-friend?bp_e=xXqWA%2B4gNXzWJ%2BRdmPRylfonBLMkpHtAM3ybYHpm7t6YPRCLQvyYwVKoyC9nQic4y3YPTWWICC0p1pEG995WgQ%3D%3D

The URL leading to your ‘refer a friend’ landing page will need to contain a bp_e parameter, which will be populated with customer’s details:

  • The full name of the customer
  • The customer’s email address
  • Whether you want to auto sign them up, or simply pre-fill the form.

Encrypting the Data:

The data inside the bp_e query string parameter must be a JSON object thats needs to be encrypted with AES256 and then converted into a Base64 encoded string.

Encoding can be achieved the following way:

  • First create a JSON object with the relevant customer details
  • Encrypt this Object using AES256 ECB mode using the first 32 characters of your account {{auth_token}} as the key, this can be provided to you by your client services manager.
  • The encrypted value should then be encoded to Base64.
  • Finally, assign this value to the bp_e query String parameter.

▶ Allowed values

The table below indicates the allowed keys which may be passed in the JSON object for encrypted signups using the bp_e parameter. These keys are also used for the plain text auto signs up which are passed to the bp_p parameter .

Parameters Description
email Email address of the customer
name Full name of the customer as FirstName LastName
auto true for automatic sign-up
false if you’d like the customer to confirm the pre-filled details
custom_field If your refer-a-friend campaign is set up to accept a custom field on the sign-up form, the value of the custom field.

Friend registrations API

Our API allows you to register new customers (friends) to your referral campaign when they register via your registration process.

You can send us either a list of users or a single customer, and we will register them as friends. You can also specify whether Buyapowa should distribute a voucher to the friends or not.

Endpoint Description
/friends/registrations To register friends to your campaign

Friend registrations API - Batch upload

The request should be made as a POST like the following example:

curl -X POST -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" -H "Content-Type: multipart/form-data;" -F "campaign_slug={{campaign_slug}}" -F "csv=@{{file.csv}}" -F "distribute_friend_voucher={{distribute_friend_voucher}}" 'https://api.co-buying.com/api/friends/registrations'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the content in a csv file:

ReferrerEmail,FriendEmail,FriendFirstName,FriendLastName,CustomFieldValue,ClientData_account_number,TermsOptIn,MarketingOptIn,Locale
john@smith.com,jane@smith.com,Jane,Smith,07123456789,552-56-3593,false,true,en
jane@doe.com,john@doe.com,John,Doe,07987654321,07987654321,662-56-3593,true,false,fr
Variable Value
{{campaign_slug}} Value to be provided by your client services manager
{{file.csv}} To be replaced by a path to your csv file
{{distribute_friend_voucher}} optional - true if you would like us to send a voucher to this friend otherwise false. If omitted, it defaults to false.. If omitted, it defaults to false.

To send us a batch of friends to register, you will need to send the details in a CSV. The CSV should have headings on the relevant columns as follows:

Header Format Example
ReferrerEmail The email address of the referrer who led the friend to register to your website. john@doe.com
FriendEmail The email address of the friend jane@smith.com
FriendFirstName The first name of the friend Jane
FriendLastName optional -The last name of the friend Smith
CustomFieldValue optional -If you are using a custom field to identify the friend, then this field may contain content such as a membership ID, or phone number 07123456789
ClientData_{{key}} optional -Extra client specified metadata associated with the friend to the campaign eg. ClientData_account_number 662-56-3593
TermsOptIn optional -Referral campaign terms & conditions acceptance of the friend, the value should be either true or false. If omitted, it defaults to false. true
MarketingOptIn optional -Marketing preferences of the friend, the value should be either true or false. If omitted, it defaults to false. true
Locale The locale of the friend. When a friend receives any emails related to the referral campaign, it will be displayed in the locale provided here. If one is not provided, it will use the default for the market en

Friend registrations API - Single upload

The request should be made as a POST like the following example:

curl -X POST -H 'auth_id: {{market_id}}' -H 'auth_token: {{auth_token}}' -H 'content-type: application/json' -d '{{json_object}}' 'https://api.co-buying.com/api/friends/registrations'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the JSON object:

{
  "campaign_slug": "{{campaign_slug}}",
  "distribute_friend_voucher": true,
  "registration": {
    "referrer_email": "john@doe.com",
    "friend_email": "jane@smith.com",
    "friend_first_name": "Jane",
    "friend_last_name": "Smith",
    "custom_field_value": "07123456789",
    "client_data": {
      "account_number": "662-56-3593"
    },
    "terms_opt_in": true,
    "marketing_opt_in": true,
    "locale": "en"
  }
}
Variable Value
{{json_object}} To be replaced by the json object itself

To send us a single friend to register, you will need to send the details as a JSON object. The JSON should be formatted as follows:

Parameter Format Example
campaign_slug
string
A value to be provided by your client services manager
distribute_friend_voucher
boolean
optional - true if you would like us to send a voucher to this friend otherwise false. If omitted, it defaults to false. true
referrer_email
string
The email address of the referrer who led this friend to register to your website. john@doe.com
friend_email
string
The email address of the friend you would like to register jane@smith.com
friend_first_name
string
The first name of the friend you would like to register Jane
friend_last_name
string
optional - The last name of the friend you would like to register Smith
custom_field_value
string
optional - If you are using a custom field to identify a friend, then this field may contain content such as a membership ID, or phone number 07123456789
client_data
string
optional - Extra client specified metadata associated with the friend you would like to register to the campaign { “account_number”: “662-56-3593” }
terms_opt_in
boolean
optional - Referral campaign terms & conditions acceptance of the friend, the value should be either true or false. If omitted, it defaults to false. true
marketing_opt_in
boolean
optional - Marketing preferences of the friend, the value should be either true or false. If omitted, it defaults to false. true
locale
string
The locale of the friend. When a friend receives any emails related to the referral campaign, it will be displayed in the locale provided here. If one is not provided, it will use the default for the market en

Data

Reports API

The API request should be made as a GET like the following example:

curl -X GET -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" "https://api.co-buying.com/api/reports/{{report_type}}/{{campaign_slug}}"

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

The expected response should be a 200 HTTP response code with the CSV data in the body.

Our Reports API lets you access useful data about your refer-a-friend campaign — on demand and in CSV format — with this API, you send a GET request each time you want to retrieve your data.

This is designed so that you can use or create your own web app to programmatically retrieve refer-a-friend data.

Variable Value
{{report_type}} the type of report you would like to download
{{campaign_slug}} value to be provided by your client services manager

▶ List of available reports

Report type Description
signups
Default time range: last 1 month
Maximum time range: 1 year
To retrieve all referrers who have signed up in the time range
friend_voucher_distribution
Default time range: last 7 days
Maximum time range: 90 days
To retrieve all the codes distributed to friends
friends
Default time range: last 7 days
Maximum time range: 90 days
To retrieve all friends. Friends who filled in the form on the friend landing page (if applicable) and/or friends who converted on your site
pending_referrals
Default time range: last 90 days
Maximum time range: 90 days
To retrieve only referrals that are pending your confirmation or cancellation
who_referred_whom
Default time range: last 7 days
Maximum time range: 90 days
To retrieve all referrals
top_referrers
Default time range: last 1 month
Maximum time range: 1 year
To retrieve the top 100 referrers based on referrals that happened in the time period
all_vouchers_distribution
Default time range: last 1 month
Maximum time range: 1 year
To retrieve all vouchers that have been distributed by the given campaign in the given time range

▶ Filter the results

Example with time range:

curl -X GET -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" "https://api.co-buying.com/api/reports/{{report_type}}/{{campaign_slug}}?starts_at=1503749083&ends_at=1506427494"

You can choose to a specific time range by including additional parameters. You can get up to 90 days data at a time.

Key Format
starts_at Unix timestamp - the number of seconds since 1970-01-01 00:00:00 UTC
ends_at Unix timestamp - the number of seconds since 1970-01-01 00:00:00 UTC

Referral Metadata

Example

Given the following bp_e query string parameter:

c%2FwMvXhEdoEvGFXKkMyzd0cxr%2BUArvqiQMVW7MgtMx2rqvfPRnC7Xaz4Ltvt%0AJfLYpbLjd%2B4ySs7228Z7AIRehpidnuBHRGtUYehcTp9epG32TP969YDqcEmo%0AVDLONgO49cOXxriOr3ydze3IcI0U1av9cTl%2B%2FDvIGxBwUp8eB1XyxH4SCget%0AS%2Bh8poKBJMpr5m5CW7Qjx%2FYZzoVgDuTsoFFYiHPz2gTgMXitWC3%2BSKau1Jp8%0A6QbjROCSAVlP%2FoTGp9FMAGTpUxUh%2BoLUMDvO17KCnDzye6DpKQvF2lsqHLlQ%0AR1KWvYqF5kEDTSVUnnzPvbPW7%2FNjGRlZy7LpQYlPXEuOCkTGDYOG3JbSbark%0ANagXwyRCmxcelzyoa8KqEirw06K1u3xNt%2B6kdtUuk%2FhqTCNHX3tx%2Fk3niSCF%0AjSYZvyyzflWcvqnevtS0U8F7EdFpOlUqW6Z3JimoKyVG9E5n7CLatqppd0Ny%0Ao1UWIzRh7Es%3D

In this example the key is fec8d49d-7f85-4884-864a-5cdc01b87cce, so you should decrypt with fec8d49d-7f85-4884-864a-5cdc01b8.

this results in the following string:

{"referral_count":0,"email":"john@doe.com","first_name":"John","last_name":"Doe","client_data":{"customer_id":"ABC123"},"custom_fields":[{"key":"mobile_number","value":"07123456789"}],"friend":{"email":"jane@smith.com","first_name":"Jane","last_name":"Smith","custom_fields":[{"key":"mobile_number","value":"07987654321"}]},"voucher_code":"QRBPFRNDE827E62E"}

This can then be parsed as a JSON object.

 {
  "referral_count": 0,
  "email": "john@doe.com",
  "first_name": "John",
  "last_name": "Doe",
  "client_data": {
    "customer_id": "ABC123"
  },
  "custom_fields": [
    {
      "key": "mobile_number",
      "value": "07123456789"
    }
  ],
  "friend": {
    "email": "jane@smith.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "custom_fields": [
      {
        "key": "mobile_number",
        "value": "07987654321"
      }
    ]
  },
  "voucher_code": "QRBPFRNDE827E62E"
}

Examples of how you could decode the metadata:

Ruby
require "openssl"
require "base64"
require "uri"
require "json"

key = "YOUR_KEY".slice(0, 32)
base64_encoded_encrypted_data = URI.unescape("YOUR_QUERY_STRING")
encrypted_data = Base64.decode64(base64_encoded_encrypted_data)

cipher = OpenSSL::Cipher.new("AES-256-ECB")
cipher.decrypt
cipher.key = key
result = cipher.update(encrypted_data) + cipher.final

JSON.parse(result)
Node.js
var crypto = require("crypto");

var decipher = crypto.createDecipheriv("aes-256-ecb", "YOUR_KEY".slice(0, 32), "");
var decrypted = decipher.update(decodeURI("YOUR_QUERY_STRING"), "base64", "utf8") + decipher.final("utf8");

return JSON.parse(decrypted);
C#/.NET
using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;

var key = Encoding.ASCII.GetBytes("YOUR_KEY".Substring(0, 32));
var base64encodedData = Uri.UnescapeDataString("YOUR_QUERY_STRING");
var encryptedData = Convert.FromBase64String(base64encodedData);

using var csp = new AesCryptoServiceProvider();
csp.KeySize = 256;
csp.BlockSize = 128;
csp.Key = key;
csp.Padding = PaddingMode.PKCS7;
csp.Mode = CipherMode.ECB;

using var decrypter = csp.CreateDecryptor();
using var ms = new MemoryStream(encryptedData);
using var cs = new CryptoStream(ms, decrypter, CryptoStreamMode.Read);
using var sr = new StreamReader(cs);

return sr.ReadToEnd();

When a user is brought to your site via a share link, we pass some extra data in the URL so you can identify:

  • the customer who brought their friend to you also known as the referrer
  • the friend who was brought to your site
  • the code distributed to the friend

Decode metadata

This data is encrypted in the query string parameter bp_e. It is a JSON object that is encrypted with AES256 and then converted into a Base64 encoded string.

You can decode the metadata by following these steps:

  1. First, take the value of the bp_e query string parameter and URI unescape it
  2. Then, Base64 decode this value
  3. Finally, decrypt it using AES256 ECB mode with the first 32 characters of your account auth_token as the key.

In the JSON

Name Description & Format Example
email
string
The email address of the referrer john@doe.com
first_name
string
The first name of the referrer, including any middle names John
last_name
string
The last name of the referrer Doe
client_data
object
Extra details from when the referrer signed up seamlessly to the campaign {"customer_id":"ABC123"}
custom_fields
array
Extra details about the referrer if your refer-a-friend campaign is set up to have a custom field on the sign-up form [{"key":"mobile_number", "value":"07123456789"}]
referral_count
integer
The number of confirmed referrals the referrer has made 0
voucher_code
string
The code distributed to the friend QRBPFRNDE827E62E
friend
object
Details of the friend being referred.
You’ll find the friend’s email, first_name, last_name and custom_fields nested in it.
Each of these nested elements are in the same format as field with the same name above

Webhooks

Using web hooks, the Buyapowa Refer-a-Friend platform can tell your system when an event has occurred. You will need to provide an endpoint for each web hook.

An example when you might use a web hook is if you want to handle your own reward delivery — you can make use of our referral confirmation hook to be notified of when a referral has occurred so you can reward your customer accordingly.

Referral confirmed

The request body will have a content type of application/json and look like the following:

{
  "campaign" : "invite-a-friend",
  "customer" : {
    "email" : "john@doe.com",
    "client_data" : { "customer_number": "123" },
    "custom_fields" : [{"label" : "Mobile", "value" : "07123456789" }],
  },
  "referral": {
    "friend" : {
        "first_name" : "Jane",
        "last_name" : "Smith",
        "email" : "jane@smith.com",
        "marketing_opt_in" : "true"
      },
      "order" : {
        "total_cents" : "4299",
        "currency" : "gbp",
        "voucher_code" : "VOUCHER42",
        "reward_category": "Bonus50",
        "order_number" : "P00337193"
      }
  },
  "total_referrals": "2"
}

This web hook will make a HTTP POST request to the given endpoint every time a referral is confirmed by the Buyapowa platform.

Name Description
customer referrer’s email as default.

Note: it will also contain any additional details you pass through to us for example client_data or custom_field.

friend details about the referred friend
order details about the order that resulted in the referral
reward_category if the order was tracked with a reward category, it will be included here
total_referrals the total number of referrals a customer has had confirmed. Useful for determining when to award rewards based on number of referrals.

Segmentation API

Customer segmentation API

Example of the GET request with the custom field labelled “membership_number” as a query string parameter:

curl -X GET "http://your-website.com/api/customer?membership_number=ABCD"

Here are the responses Buyapowa will expect from your servers:

Code Description
200 If the customer is allowed to sign up to the campaign
404 If the customer is not allowed to sign up to the campaign

When a customer visits your refer-a-friend campaign they are presented with a form to sign up to the refer-a-friend campaign. By default, this page ask for the customer’s full name and their email address. We can configure this page to have a custom field to ask for an additional piece of information such as their membership number, mobile number, postcode, etc.

When they submit the form with the information required to sign up to the campaign, Buyapowa can send this additional information to your servers, and your servers can determine whether this customer should be allowed to sign up to the campaign or not.

Buyapowa’s servers perform a GET request with the custom field value as query string parameter and will expect the correct response from your servers.

▶ Security

Buyapowa will only integrate with API’s that implement http authentication, as well as SSL (TLS) for data security.

▶ Custom implementation

If your implementation must be very different from this, please contact the client services team at Buyapowa to ensure your requirements can be accommodated.

Friend segmentation API

Buyapowa’s servers perform a GET request with the email address as query string parameter, for example:

curl -X GET "http://your-website.com/api/customer?email=customer@email.com"

When a friend comes through a referrers sharing link, they can be presented with a page to request a voucher code. We can configure this page to ask for some information such as email address. This API can be used:

  • to restrict the distribution of the friend incentive to a specific segment of customers.
  • to distribute different incentive per segment of customers.

Here are the responses Buyapowa will expect from your servers:

Code Description
200 If the user exist and is therefore not allowed to get the incentive
404 If the user doesn’t exist and is therefore eligible for the incentive

Buyapowa’s servers perform a GET request with the email address as query string parameter and will expect the correct response from your servers.

▶ Security

Buyapowa will only integrate with API’s that implement http authentication, as well as SSL (TLS) for data security.

▶ Custom implementation

If your implementation must be very different from this, please contact your client services team at buyapowa to ensure you requirements can be accommodated.

Subscription API

Our API allows you to unsubscribe or re-subscribe a user of the refer-a-friend campaign.

You can send us either a batch of users or a single user at a time to unsubscribe or re-subscribe to the refer-a-friend operational emails.

List of endpoints available:

Endpoint Description
/subscriptions/subscribe To subscribe a refer-a-friend user to the refer-a-friend operational emails
/subscriptions/unsubscribe To unsubscribe a refer-a-friend user from the refer-a-friend operational emails

Subscription API - Batch upload

The request should be made as a POST like the following example:

curl -X POST -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" -H "Content-Type: multipart/form-data;" -F "csv=@{{file.csv}}" 'https://api.co-buying.com/api/{{endpoint}}'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the content in a csv file:

Email
john@doe.com
jane@smith.com
Variable Value
{{file.csv}} To be replaced by a path to your csv file

To send us a batch of users to update, you will need to send the details in a CSV. The CSV should have headings on the relevant columns as follows:

Header Format Example
Email The email address of the user you would like to subscribe or unsubscribe john@doe.com

Subscription API - Single upload

The request should be made as a POST like the following example:

curl -X POST -H 'auth_id: {{market_id}}' -H 'auth_token: {{auth_token}}' -H 'content-type: application/json' -d '{{json_object}}' 'https://api.co-buying.com/api/{{endpoint}}'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the JSON object:

{
  "user" : {
    "email" : "john@doe.com"
  }
}
Variable Value
{{json_object}} To be replaced by the json object itself

To send us a single user to update, you will need to send the details as a JSON object. The JSON should be formatted as follows:

Parameter Format Example
email
string
The email address of the user you would like to subscribe or unsubscribe john@doe.com


Forget users API

Our API allows you to remove a user’s data from our system when they made a request to be forgotten.

You can send us either a list of users or a single user who have made a request for erasure and we will erase their personal data from our system.

Once a user’s personal data is erased from our system, they will no longer be able to use the refer-a-friend campaign unless they decide to sign up again to the campaign.

Endpoint Description
/users/forget To erase a user’s personal data from our system

Forget users API - Batch upload

The request should be made as a POST like the following example:

curl -X POST -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}" -H "Content-Type: multipart/form-data;" -F "csv=@{{file.csv}}" 'https://api.co-buying.com/api/users/forget'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the content in a csv file:

Email
john@doe.com
jane@smith.com
Variable Value
{{file.csv}} To be replaced by a path to your csv file

To send us a batch of users who have made a request to be forgotten, you will need to send the details in a CSV. The CSV should have headings on the relevant columns as follows:

Header Format Example
Email The email address of the user who requested to be forgotten john@doe.com

Forget users API - Single upload

The request should be made as a POST like the following example:

curl -X POST -H 'auth_id: {{market_id}}' -H 'auth_token: {{auth_token}}' -H 'content-type: application/json' -d '{{json_object}}' 'https://api.co-buying.com/api/users/forget'

Note: North American clients only - please use the co-buying.net domain instead of co-buying.com

Example of the JSON object:

{
  "user" : {
    "email" : "john@doe.com"
  }
}
Variable Value
{{json_object}} To be replaced by the json object itself

To send us a single user who has made a request to be forgotten, you will need to send the details as a JSON object. The JSON should be formatted as follows:

Parameter Format Example
email
string
The email address of the user who requested to be forgotten john@doe.com

General API info

Buyapowa offers a number of APIs to support more sophisticated campaign setups, the details of which you can find in individual sections in this documentation. All of our APIs follow the same authentication process and responses as outlined below.

Responses

Here are the responses you can expect from our APIs.

Code Scenario Example
200 (POST) Your request was understood. If there are problems with your submission, they are noted in the response body. The uploaded CSV is missing a required column / Referral not created
200 (GET) Your request was successful -
201 Your submission was successful and has resulted in a creation Referral created
202 Your submission has no problems and is being processed -
303 Your request has been accepted and the results can be found at the location provided -
401 Your request was not authorised The wrong auth_id/auth_token combination is given
404 The requested resource is not found The wrong ID of the resource is given
422 There was a problem with your request and the reason(s) will be noted in the response body Where a CSV is required, an XLS file is uploaded
429 You’ve reached the rate limit -
500 An unexpected error has occurred -

Authentications

Authentication requires an auth_id (which is your market_id) and an auth_token to be added to the headers of your requests.

They should be added to requests as detailed below:

curl -H "auth_id: {{market_id}}" -H "auth_token: {{auth_token}}"

Code Description Format
{{auth_id}} The value should be your Market ID - value to be provided by your client services manager UUID
{{auth_token}} The value should be your Auth token - value to be provided by your client services manager UUID

For more specific responses, please refer to the documentation for the API you are using.

Limits

Our API imposes some limits:

Type Description
Rate limits If a request exceeds the limit we will return a 429 error.
Result limits this limit is applied to the volume of data you can get from our platform. If a request exceeds the limit we will return a 422 error, the reason(s) will be noted in the response body.
Playload limits this limit is applied to the volume of data you post to our platform. If a request exceeds the limit we will return a 422 error, the reason(s) will be noted in the response body.

Shopify guide

Code to add at step 4

<script src="//cdn.co-buying.com/embedding.min.js"></script>
<meta property="og:url" content="https://{{market_domain}}/iaf/{{campaign_slug}}/og" />

Code to add at step 7

<div id="bp_div">
  <script type="text/javascript">
      var buyapowa = new Buyapowa({url: "https://{{market_domain}}", market: "{{market}}"}, "bp_div");
      buyapowa.embedReferAFriend({
          "campaign": "{{campaign_slug}}"
      });
  </script>
</div>

Code to add at step 9

{% assign voucher = checkout.discounts | first %}
<script src="//cdn.co-buying.com/embedding.min.js"></script>
<script type="text/javascript">
  window.onload = function() {
    var buyapowa = new Buyapowa({url: "https://{{market_domain}}", market: "{{market}}"});
    buyapowa.track({
      "customer_name": "{{ customer.first_name }}, {{ customer.last_name }}",
      "customer_email": "{{ customer.email }}",
      "order_value": "{{ total_price | money_without_currency }}",
      "campaign": "{{campaign_slug}}",
      "order_number": "{{ order_number }}",
      "voucher_code": "{{ voucher.code }}",
      "marketing_opt_in": "{{ customer.accepts_marketing }}"
    });
  };
</script>

Your refer-a-friend campaign lives on one of your web pages. Using the Buyapowa client library, you will embed on this page the refer-a-friend campaign powered by Buyapowa and you will track referral conversions.

Variable Value
{{market_domain}} value to be provided by your client services manager
{{campaign_slug}} value to be provided by your client services manager

This is a step-by-step guide on how to integrate with Shopify:

Adding the Buyapowa library

1. Go to the Themes section in your Shopify admin

2. Click the “…” button and click “Edit HTML/CSS”

3. Select the “theme.liquid” under the “layout” heading

4. Add the relevant code just before the </head> tag

Creating your refer-a-friend page

5. Under the Template section click “Add a new template…”

6. Create a new template for a page called refer-a-friend and click the button “Create template”

7. Add the relevant code to the template “page.refer-a-friend.liquid” and save the changes

Track referral conversions with Shopify

8. Go to the settings section in your Shopify admin

9. Paste the relevant code into the “Additional scripts” section, this will add the tracking script to your ‘Order status page’.

External mailer

If you would like to send some emails yourselves instead of relying on our emails, Buyapowa can notify your system to send relevant emails when an event happens in the our system, a HTTPS webhook URL can be called to send emails via your own system.

Notifications

Requests to the webhook URLs you give us are sent as HTTP POST with a JSON body containing all the necessary information required.

All requests will have the following standard information, plus additional information depending on the type of email.

Parameter Description
key The type of email to trigger
to Whom this email should be sent to
user Who initiated the email - this may or may not be the same as whom it is addressed to.
Nested in this object, you’ll find the first_name, last_name, email and marketing_opt_in of the user.

▶ Auto-invite email

Example

{
  "key": "auto_invite",
  "to": "test@customer.com",
  "user": {
    "email": "test@customer.com",
    "first_name": "Tracy",
    "last_name": "Testerson",
    "marketing_opt_in": "true"
  },
  "dashboard_url": "https://example.com/refer-a-friend"
}

When a customer on the client site purchases, sent after a set period of time to incentivise new referring users.

Parameter Description
dashboard_url A link that will drive the user to sign up to the refer-a-friend campaign

▶ Signed up confirmation email

Example

{
  "key": "sign_up_confirmation",
  "to": "test@customer.com",
  "user": {
    "email": "test@customer.com",
    "first_name": "Tracy",
    "last_name": "Testerson",
    "marketing_opt_in": "true"
  },
  "dashboard_url": "https://example.com/refer-a-friend",
  "share_url": "http://referme.to/abc123o"
}

When a user signs up to your campaign, or asks to receive their sign up confirmation email.

Parameter Description
dashboard_url A link that will return the user to their referral dashboard on your site
share_url The link the user can share with their friends, to get them to your site. This url SHOULD NEVER BE presented as a HYPERLINK

▶ Reminder email

Example

{
  "key": "reminder",
  "to": "test@customer.com",
  "user": {
    "email": "test@customer.com",
    "first_name": "Tracy",
    "last_name": "Testerson",
    "marketing_opt_in": "true"
  },
  "dashboard_url": "https://example.com/refer-a-friend",
  "share_url": "http://referme.to/abc123o"
}

Sent after a certain period of time has elapsed after sign up (in days), to any customers without any referrals (or to all customers).

Parameter Description
dashboard_url A link that will return the user to their referral dashboard on your site
share_url The link the user can share with their friends, to get them to your site. This url SHOULD NEVER BE presented as a HYPERLINK

▶ Referrer Reward email

Example

{
  "key": "referrer_reward",
  "to": "test@customer.com",
  "user": {
    "email": "test@customer.com",
    "first_name": "Tracy",
    "last_name": "Testerson",
    "marketing_opt_in": "true"
  },
  "dashboard_url": "https://example.com/refer-a-friend",
  "friends_first_name": "Brian",
  "primary_voucher": {
    "name": "50% off",
    "type": "text",
    "code": {
      "value": "ABC123",
      "image_url": ""
    }
  },
  "secondary_voucher": {
    "name": "50% off",
    "type": "EAN13",
    "code": {
      "value": "1234567890128",
      "image_url": "https://co-buying.com/barcode/ean_13?data=1234567890128"
    }
  },
  "total_referrals": "1"
}

When a customer gets a voucher reward after referring a friend (reward per referral) or when reaching a certain number of referrals (tiered rewards)

Parameter Description
dashboard_url A link that will return the user to their referral dashboard on your site
friends_first_name The name of the friend who was referred
reward_name The reward name, this will be useful if you decide to do tiered reward in addition to reward per referral
primary_voucher Voucher code that should be given to the user as a reward for referring
secondary_voucher Voucher code that should be given to the user as a reward for referring
total_referrals The total number of referrals made by the referrer

Nested within primary_voucher & secondary_voucher, you will find:

  • the name of the voucher, this is useful if you decide to do tiered reward in addition to reward per referral
  • the type of code (text - QR code - EAN13)
  • the voucher code as a string
  • a url of an image of the code if the code is a QR code or a barcode

▶ Friend incentive email

Example

{
  "key": "friend_incentive",
  "to": "test@customer.com",
  "user": {
    "email": "test@customer.com",
    "first_name": "Tracy",
    "last_name": "Testerson",
    "marketing_opt_in": "true"
  },
  "destination_url": "https://example.com",
  "referrers_first_name": "Brian",
  "primary_voucher": {
    "name": "50% off",
    "type": "text",
    "code": {
      "value": "ABC123",
      "image_url": ""
    }
  },
  "secondary_voucher": {
    "name": "50% off",
    "type": "EAN13",
    "code": {
      "value": "1234567890128",
      "image_url": "https://co-buying.com/barcode/ean_13?data=1234567890128"
    }
  }
}

When a friend gets a voucher code as an incentive to shop

Parameter Description
destination_url A link that will return the user to the friend destination URL on your site.
referrers_first_name The name of the referrer who referred them.
primary_voucher Details about the primary voucher code that should be given to the user as an incentive to complete an action.
secondary_voucher The secondary voucher code that should be given to the user as an incentive to complete an action.

Nested within primary_voucher & secondary_voucher, you will find:

  • the name of the voucher, this is useful if you decide to do tiered reward in addition to reward per referral
  • the type of code (text - QR code - EAN13)
  • the voucher code as a string
  • a url of an image of the code if the code is a QR code or a barcode

▶ Friend incentive reminder email

Example

{
  "key": "friend_incentive_reminder",
  "to": "test@customer.com",
  "user": {
    "email": "test@customer.com",
    "first_name": "Tracy",
    "last_name": "Testerson",
    "marketing_opt_in": "true"
  },
  "destination_url": "https://example.com",
  "referrers_first_name": "Brian",
  "primary_voucher": {
    "name": "50% off",
    "type": "text",
    "code": {
      "value": "ABC123",
      "image_url": ""
    }
  },
  "secondary_voucher": {
    "name": "50% off",
    "type": "EAN13",
    "code": {
      "value": "1234567890128",
      "image_url": "https://co-buying.com/barcode/ean_13?data=1234567890128"
    }
  }
}

When a friend hasn’t redeemed their voucher code X days after having received the friend_incentive email.

Parameter Description
destination_url A link that will return the user to the friend destination URL on your site.
referrers_first_name The name of the referrer who referred them.
primary_voucher Details about the primary voucher code that should be given to the user as an incentive to complete an action.
secondary_voucher The secondary voucher code that should be given to the user as an incentive to complete an action.

Nested within primary_voucher & secondary_voucher, you will find:

  • the name of the voucher, this is useful if you decide to do tiered reward in addition to reward per referral
  • the type of code (text - QR code - EAN13)
  • the voucher code as a string
  • a url of an image of the code if the code is a QR code or a barcode