ReferralCandy API

Introduction


The ReferralCandy API provides a simple interface with JSON-formatted responses to integrate your store with the ReferralCandy referral platform.

ReferralCandy API calls are made to the following URL:

https://my.referralcandy.com/api/v1/some-method.json

(Please note that all API input should be encoded in UTF-8.)

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:

  1. Gather the API call parameters into an array of strings of the format"parameter_name=parameter_value".
  2. Sort the name/value pairs in the array.
  3. Join the array elements into a string.
  4. Prepend the API Secret Key to the string to form a combined string.
  5. The signature is the MD5 of this combined string.

A sample signature calculation is as follows:

  1. ["timestamp=1296664909", "accessID=acihijaklscj", "name=john"]
  2. ["accessID=acihijaklscj", "name=john", "timestamp=1296664909"]
  3. "accessID=acihijaklscjname=johntimestamp=1296664909"
  4. "APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909"
  5. 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.

HTTP CodeMeaning
200API call was successful.
400You've made an error in your request. See the message field in the response for details.
401Authentication credentials provided were incorrect.
404Unknown API method.
500A temporary internal server error.

API Methods


Verify Method

Overview

This method lets you verify that authentication for your API calls is set up correctly.

URL

https://my.referralcandy.com/api/v1/verify.json

Request Method

GET

Input Parameters

FieldDescriptionRequired
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call.

Sample Result

{"message":"Verification Ok"}

Purchase Method

Overview

This method lets you register a new purchase at your store. A referral email will be sent to the customer.

URL

https://my.referralcandy.com/api/v1/purchase.json

Request Method

POST

Input Parameters

FieldDescriptionRequired
first_nameCustomer's first name.yes
last_nameCustomer's last name.no
emailCustomer's email address.yes
localeCustomer's preferred language. Defaults to campaign's default language if it is not set or not available to the campaign. This is a complete list of valid values (ISO 639-1 language code): en, fr, de, es, it, ja, nl, ru, zh-CN, zh-HK, zh-TW, da, no, sv, pt-BR.no
discount_codeDiscount code used in the order. Blank if no discount code was used.yes if discount code was used
accepts_marketingWhether the customer opted in to marketing (true/false). Defaults to true.no
order_timestampUNIX timestamp of order.yes
browser_ipIP address of customer when making the purchase.yes
user_agentUser agent string of the customer's web browser.yes
invoice_amountTotal invoice amount for this purchase.yes
currency_codeISO 4217 currency code used in order invoice (e.g. USD, GBP, INR).yes
external_reference_idAn ID that can be used to track this purchase externally.no
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call.
referralcorner_urlURL of the new customer's Portal Sharing Page.

Sample Result

{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X"}

Referrals Method

Overview

This method lets you query for referred purchases made over some period of time.

URL

https://my.referralcandy.com/api/v1/referrals.json

Request Method

GET

Input Parameters

FieldDescriptionRequired
period_fromUNIX timestamp of start of query period.yes
period_toUNIX timestamp of end of query period. Defaults to most recent timestamp.no
customer_emailAdvocate's email address. Return referred purchases made by advocate if set. Return all referred purchases if not set.no
pending_review_onlyWhether to only return referred purchases that are pending the review period (true/false). Defaults to false - this returns referred purchases regardless of review period status.no
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
referralsArray of referred customers and referral timestamps.

FieldDescription
referral_emailEmail address of referred customer.
referral_timestampUNIX timestamp when referral purchase was made.
referring_emailEmail address of advocate who made the referral.
review_period_overWhether the review period for this referred purchase is over.
external_reference_idAn ID that can be used to track this referred purchase externally.
period_fromUNIX timestamp of start of query period.
period_toUNIX timestamp of end of query period of the results returned. This might not be the same as the period_to value requested since successful referrals can only be detected up till a couple of minutes before the current time.
messageA message indicating the outcome of the API call.

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.

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

FieldDescriptionRequired
customer_emailEmail address of customer who made the referred purchase.yes
notifyWhether to notify customer who referred customer specified above that the referral has been disregarded (true/false). Defaults to true.no
returnedWhether customer has returned his/her purchase (true/false). If 'returned' is set to true, the referral will be disregarded and rewards will not be paid out.yes
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call.
customer_emailCustomer email address.
returnedWhether customer has returned his/her purchase.

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.

URL

https://my.referralcandy.com/api/v1/referrer.json

Request Method

GET

Input Parameters

FieldDescriptionRequired
customer_emailCustomer email address.yes
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
referrerEmail address of referring customer if one exists, null otherwise.
messageA message indicating the outcome of the API call.

Sample Result

{"message":"Success","referrer":"referrer@example.com"}

Contacts Method

Overview

This method lets you query for contacts involved in your referral campaign.

Example:
Query with id = 50 and limit = 100 will return the 100 contacts invited to your referral campaign after (and including) contact with id = 50.

URL

https://my.referralcandy.com/api/v1/contacts.json

Request Method

GET

Input Parameters

FieldDescriptionRequired
idLowest id of contact returned by query. Defaults to 1.no
limitNumber of contacts to return. Defaults to 100. Capped at 100.no
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
contactsArray of contacts.

FieldDescription
idUnique identifier of contact.
first_nameFirst name of contact.
last_nameLast name of contact.
emailEmail address of contact.
purchase_madeWhether contact made a purchase at the store (true/false).
purchasesArray of purchases made by contact.
FieldDescription
purchased_atUNIX timestamp of purchase.
amountInvoice amount of purchase.
unsubscribedWhether contact is unsubscribed (true/false).
total_countTotal number of contacts involved in your referral campaign to date.
messageA message indicating the outcome of the API call.

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 sign an advocate up for your referral program. If the advocate already exsits, you can use this method to retrieve the advocate's referral link and Portal Sharing Page address.

URL

https://my.referralcandy.com/api/v1/signup.json

Request Method

POST

Input Parameters

FieldDescriptionRequired
first_nameAdvocate's first name.yes
last_nameAdvocate's last name.yes
emailAdvocate's email address.yes
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call.
referralcorner_urlURL of the advocate's Portal Sharing Page.
referral_linkURL of the advocate's unique referral link.

Sample Result

{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X","referral_link":"http://refcandy.refr.cc/ABCDEF"}

Invite Method

Overview

This method lets you send out an in-app invite to a contact. This counts against your in-app invite quota.

URL

https://my.referralcandy.com/api/v1/invite.json

Request Method

POST

Input Parameters

FieldDescriptionRequired
emailContact's email address.yes
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call.
inviteThe number of in-app invites remaining for your campaign.

Sample Result

{"message":"Success","invites":500}

Unsubscribed Method

Overview

This method lets you unsubscribe and resubscribe a contact in your referral program.

URL

https://my.referralcandy.com/api/v1/unsubscribed.json

Request Method

PUT

Input Parameters

FieldDescriptionRequired
emailContact's email address.yes
unsubscribedWhether to unsubscribe or resubscribe contact (true/false).yes
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call.
emailCustomer email address.
unsubscribedWhether customer is unsubscribed.

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.

URL

https://my.referralcandy.com/api/v1/rewards.json

Request Method

GET

Input Parameters

FieldDescriptionRequired
emailWhen given, the result only contains rewards from the advocate with this email address.no
since_idWhen given, the result starts from the next matching reward earned after the specified reward ID. Otherwise, the result starts with the first matching reward.no
statusWhen specified, the result contains rewards with the matching status. Otherwise, the result contains rewards matching all statuses. Accepted values are pending_fulfillment, delivered.no
typeWhen specified, the result contains rewards with the matching type. Otherwise, the result contains rewards matching all types. Accepted values are cash, coupon, custom, none.no
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call.
rewardsThe first 200 matching rewards.
since_idThe value specified in the request if available.
statusThe value specified in the request if available.
typeThe value specified in the request if available.

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}

Post Rewards Method

Overview

This method lets you update a custom reward.

URL

https://my.referralcandy.com/api/v1/rewards.json

Request Method

POST

Input Parameters

FieldDescriptionRequired
idThe ID of the reward.yes
statusThe status of the reward. Accepted values are pending_fulfillment, delivered.yes
timestampUNIX timestamp of API call.yes
accessIDAPI Access ID.yes
signatureCalculated signature.yes

Output Parameters

FieldDescription
messageA message indicating the outcome of the API call if available.
messagesA list of messages indicating the outcome of the API call if available.
rewardThe updated reward.

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...")
Shopify Logo

Available On The

Shopify App Store