.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/v2/verify.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","status":"success"}Campaigns Method
Overview
This method retrieves a list of all campaigns associated with your account or a specific client. It returns campaign IDs, names, and join URLs that can be used for integration with other API endpoints. This is particularly useful for discovering available campaigns and their identifiers for use with campaign-specific operations like signup, contacts, and invite endpoints. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.
Example
Your account has multiple referral/affiliate campaigns running. Use the Campaigns API to retrieve all available campaigns, then use the campaign IDs to enroll customers or fetch campaign-specific data through other endpoints.
URL
https://my.referralcandy.com/api/v2/campaigns.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{
"message": "Success",
"campaigns": [
{
"campaign_id": 123456,
"campaign_name": "Summer Referral Program",
"join_url": "https://mystore.referralcandy.com/join/summer2024"
},
{
"campaign_id": 789012,
"campaign_name": "VIP Customer Rewards",
"join_url": "https://mystore.referralcandy.com/join/vip-rewards"
}
]
}Purchase Method
Overview
This method lets you register a new purchase at your store and get referral URLs for all enrolled campaigns. 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/purchase.json
Request Method
POST
Input Parameters
Output Parameters
Sample Results
{"message":"Success","status":"success","referralcorner_urls":[{"campaignId":123456,"url":"https://mystore.referralcandy.com/ABC123"},{"campaignId":789012,"url":"https://vip.referralcandy.com/XYZ789"}]}
{"message":"Success","status":"success","referralcorner_urls":[]}
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/v2/referrals.json
Request Method
GET
Input Parameters
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 track a referral purchase and attribute it to the referrer. 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/referral.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","campaignId":123456}
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/v2/referrer.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{"message":"Success","referrer":"john@example.com","campaignId":123456}
Contacts Method
Overview
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/v2/contacts.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{"message":"Success","campaignId":123456,"contacts":[{"email":"john@example.com","firstName":"John","lastName":"Doe","referralCode":"JOHN123","referralUrl":"https://mystore.referralcandy.com/JOHN123","enrolledAt":"2024-01-01T00:00:00Z","referralsCount":5,"rewardsEarned":3,"status":"active"}],"total":150,"limit":10,"offset":0}
Signup Method
Overview
This method lets you enroll a contact into a specific campaign. This method is not available when the campaign is paused or stopped and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v2/signup.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","status":"success","referralcorner_url":"https://mystore.referralcandy.com/ABC123"}
Invite Method
Overview
This method lets you send campaign-specific invitation emails to contacts. This method is not available when the campaign is paused or stopped and will return a HTTP 403 Forbidden status code.
URL
https://my.referralcandy.com/api/v2/invite.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","invitesSent":2,"campaignId":123456}
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/v2/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 for contacts, optionally filtered by campaign. 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","campaignId":123456,"rewards":[{"id":"RWD001","email":"john@example.com","type":"cash","amount":10.00,"currency":"USD","status":"delivered","earnedAt":"2024-01-15T10:00:00Z","deliveredAt":"2024-01-16T09:00:00Z","referralInvoice":"INV-67890"}],"total":45,"limit":20,"offset":0}
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/v2/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/v2/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...")
