.png)
ReferralCandy API
Introduction
The ReferralCandy API provides a simple interface with JSON-formatted responses to integrate your store with the ReferralCandy referral platform.
Please note that all API input should be encoded in UTF-8.
Please note that all timestamps used in our API must be in Unix time format (seconds). For example, use 1625078400 for June 30, 2021, 00:00:00 UTC. Do not use milliseconds (e.g., 1625078400000) or ISO 8601 (e.g., 2021-06-30T00:00:00Z)
Authentication
Each call to the ReferralCandy API requires the sending of the current UNIX timestamp, Access ID and signature parameters. Your API Access ID can be found on your account settings page. The signature parameter is generated from your API Secret Key which can also be found on your account settings page.
To generate the signature for a particular call to the API, carry out the following steps:
Gather the API call parameters into an array of strings of the format"parameter_name=parameter_value".
Sort the name/value pairs in the array.
Join the array elements into a string.
Prepend the API Secret Key to the string to form a combined string.
The signature is the MD5 of this combined string.
A sample signature calculation is as follows:
["timestamp=1296664909", "accessID=acihijaklscj", "name=john"]
["accessID=acihijaklscj", "name=john", "timestamp=1296664909"]
"accessID=acihijaklscjname=johntimestamp=1296664909"
"APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909"
signature = MD5("APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909") = "04535fe455e9f77a90c06e81d7888569"
Response Codes
The ReferralCandy API uses standard HTTP status codes to indicate success or failure of API calls.
API Methods
Verify Method
Overview
This method lets you verify that authentication for your API calls is set up correctly. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/verify.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
Purchase Method
Overview
This method lets you register a new purchase at your store. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/purchase.json
Request Method
POST
Input Parameters
The referrer_id will be used to help identify who referred this purchase.
Output Parameters
Sample Results
{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X"}
{"message":"Success"}
Referrals Method
Overview
This method lets you query for referred purchases made over some period of time. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/referrals.json
Request Method
GET
Output Parameters
Sample Result
{"message":"Success","referrals":[{"referral_email":"referral1@example.com","referral_timestamp":1329738979,"referring_email":"customer@example.com"},{"referral_email":"referral2@example.com","referral_timestamp":1329738984,"referring_email":"customer@example.com"}],"period_from":1329738679,"period_to":1329739284}
Referral Method
Overview
This method lets you update the purchase status of a referred customer. By default, an email is sent out to the customer who made the referral to inform him/her that he/she is not eligible for a recent referral reward. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
Example:
Bob makes a purchase at your store, referred by Amy. Bob returns his purchase. Make an 'Update Referral' API call, and set 'returned' to true. By default, Amy gets an email informing her that she is no longer eligible for the referral reward.
URL
https://my.referralcandy.com/api/v1/referral.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","customer_email":"customer@example.com","returned":true}
Referrer Method
Overview
This method lets you query for the referrer of a particular customer. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/referrer.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{"message":"Success","referrer":"referrer@example.com"}
Contacts Method
Overview
This method lets you query for contacts currently enrolled in your first campaign. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
Example:
Query with id = 50 and limit = 100 will return the 100 contacts invited to your first campaign after (and including) contact with id = 50.
URL
https://my.referralcandy.com/api/v1/contacts.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{"message":"Success","total_count":400,"contacts":[{"id":800,"first_name":"Contact","last_name":"One","email":"contact1@example.com","purchase_made":true,"purchases":[{"purchased_at":1329738679,"amount":97.0}],"unsubscribed":false},{"id":1250,"first_name":"Contact","last_name":"Two","email":"contact2@example.com","purchase_made":false,"purchases":[],"unsubscribed":false}]}
Signup Method
Overview
This method lets you add a contact to the ReferralCandy system. If the advocate is enrolled in the first campaign, you can use this method to retrieve the advocate's referral link and Portal Sharing Page address for the first campaign. This method is not available when the first campaign is paused or stopped and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/signup.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X","referral_link":"http://refcandy.refr.cc/ABCDEF","invite_code":"BW299X"}
Invite Method
Overview
This method lets you send out an invite email to a contact for your first campaign if the contact is enrolled in it. This method is not available when your first campaign is paused or stopped and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/invite.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","invites":500}
Unsubscribed Method
Overview
This method lets you unsubscribe and resubscribe a contact in your referral program. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/unsubscribed.json
Request Method
PUT
Input Parameters
Output Parameters
Sample Result
{"message":"Success","email":"contact1@example.com","unsubscribed":true}
Get Rewards Method
Overview
This method lets you query for rewards which match some criteria. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v2/rewards.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{:message=>"Success", :rewards=>[{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>2, :status=>"delivered", :type=>"custom"}, {:advocate_email=>"alice@example.com", :advocate_name=>"Alice Bob", :created_at=>1442584426, :description=>"20% discount", :id=>3, :status=>"pending_fulfilment", :type=>"custom"}], :since_id=>1}
Reward Purchases Method
Overview
This method lets you query for the referred purchases that are associated with a reward. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/reward_purchases.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{"message":"Success", "referred_purchases":[{"id":1, "external_reference_id":"ORDER_1", "purchaser_email":"john@example.com"},{"id":2, "external_reference_id":"ORDER_2", "purchaser_email":"alice@example.com"}]}
Post Rewards Method
Overview
This method lets you update a custom reward. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v1/rewards.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{:message=>"Success", :reward=>{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>3938282, :status=>"delivered", :type=>"custom"}}
Troubleshooting
Signature Calculation
A common mistake is that the same URI encoded API params for making a POST request are also used to compute the signature.
For example, if you had the following params:
{email: "abc@xyz.com", name: "john & jane"}
Your POST body would be URI encoded:
email=abc%40xyz.com&name=john+%26+jane
However, your MD5 should be computed with the literal string (not the URI encoded string):
MD5("...email=abc@xyz.comname=john & jane...")
