Before Starting

API Integration requires experience in programming. If you are not a developer, either consult one or try Email Integration. Unfortunately, we do not provide debugging support for this.
 
 You should use API integration because:

  1. You cannot bcc: ReferralCandy in your invoice emails, so Email Integration does not work for your store.
  2. You cannot expose dynamic checkout variables needed for JavaScript Integration.
  3. You want to do a custom integration with your existing rewards system.
  4. You have a non-standard checkout process for your online store, e.g. the invoice information is finalized some time after the initial JavaScript tracking code is triggered.

How API Integration works

(1) Insert the referral tracking code snippet on your store's purchase completed page. Paste the code just before the </body> tag.

(2) A referrer signs up by visiting the link found at the top of your themes page, obtaining his invite link.

(3) From another browser and IP address, another person is referred by visiting the referrer's invite link, and then the purchase completed page of your store.

(4) Use the purchase method of the ReferralCandy API to send ReferralCandy purchase information to detect referrals. In particular:

  • the order_timestamp field must be within 10 minutes of the visit to your store's purchase completed page
  • the browser_ip and user_agent fields must correspond with the IP address and browser used by the purchase at step (3) above

curl --data "accessID=THISISMYACCESSID&browser_ip=173.255.155.102&currency_code=USD&email=example@referralcandy.com&external_reference_id=1234&first_name=ReferralCandy&invoice_amount=100.0&last_name=Example&order_timestamp=1581002448&timestamp=1581062448&signature=SIGNATUREASCALCULATEDBELOW" --data-urlencode "user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:72.0) Gecko/20100101 Firefox/72.0" https://my.referralcandy.com/api/v1/purchase.json

You can also use other methods of our API to carry out a more customized integration with ReferralCandy. View API Documentation.

(5) You should see referrals detected for the referrer on his contacts page.

Tips for using the purchase method of ReferralCandy API

Provide all of the required fields for a particular API method and include them all in calculating the signature field.
If you provide non-required fields, make sure that they are also included as part of signature calculation.

Sort all the name/value pairs in alphabetical order
If you have non-required fields, they should also be sorted with the required fields in alphabetical order.

Specify a timestamp that is within the past hour

The timestamp field specified must be within an hour from the time of the API call.
Use the correct values for the Access ID and Secret Key

Both the Access ID and Secret Key can be found in the "API Tokens" section of your profile page.

Worked example to calculate signature

Here is how you would calculate the signature for the Purchase Method of the API.

(1) Gather all the field/value pairs, ensuring that all required fields have values

List of required fields used in this example to calculate the signature field
first_name=ReferralCandy
email=
example@referralcandy.com
order_timestamp=1581002448
browser_ip=173.255.155.102
user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:72.0) Gecko/20100101 Firefox/72.0
invoice_amount=100.0
currency_code=USD
timestamp=1581062448
accessID=THISISMYACCESSID

List of non-required fields
last_name=Example
external_reference_id=1234

(2) Sort all the field/value pairs in alphabetical order

accessID=THISISMYACCESSID
browser_ip=173.255.155.102
currency_code=USD
email=
example@referralcandy.com
external_reference_id=1234
first_name=ReferralCandy
invoice_amount=100.0
last_name=Example
order_timestamp=1581002448
timestamp=1581062448
user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:72.0) Gecko/20100101 Firefox/72.0


(3) Join all the field/value pairs into a single string

accessID=THISISMYACCESSIDbrowser_ip=173.255.155.102currency_code=USDemail=example@referralcandy.comexternal_reference_id=1234first_name=ReferralCandyinvoice_amount=100.0last_name=Exampleorder_timestamp=1581002448timestamp=1581062448user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:72.0) Gecko/20100101 Firefox/72.0

(4) Prepend your API Secret Key to this string

THISISMYSECRETKEYaccessID=THISISMYACCESSIDbrowser_ip=173.255.155.102currency_code=USDemail=example@referralcandy.comexternal_reference_id=1234first_name=ReferralCandyinvoice_amount=100.0last_name=Exampleorder_timestamp=1581002448timestamp=1581062448user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:72.0) Gecko/20100101 Firefox/72.0

(5) The signature field is the MD5 hash of this string

require "digest/md5"

Digest::MD5.hexdigest("THISISMYSECRETKEYaccessID=THISISMYACCESSIDbrowser_ip=173.255.155.102currency_code=USDemail=
example@referralcandy.comexternal_reference_id=1234first_name=ReferralCandyinvoice_amount=100.0last_name=Exampleorder_timestamp=1581002448timestamp=1581062448user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:72.0) Gecko/20100101 Firefox/72.0")

=> "c4c5c55b142494e8dfcaf4e806900223"


Did this answer your question?