Welcome, Guest Login

Support Center

Advanced Integration (API)

Last Updated: May 31, 2016 07:56AM UTC
Before diving in, please pay special attention to the following as we know your time is precious:
  • Implementing this integration option will require technical experience in programming so please have a read through and if it seems complicated, please either consult your developer or use our Standard Integration option instead as regrettably we will not be able to provide debugging consultation

With API Integration, you would still need to insert the JavaScript tracking code snippet from the Standard Integration.

However instead of sending ReferralCandy the invoice or extract email, you would use the 
purchase method of our API.

You can also use the other methods of our API to carry out a more customized integration with ReferralCandy. More information about our API can be 
found here.
API integration gives you full flexibility to customize your referral program. In general, it can be used when:
  1. You're unable to copy ReferralCandy on invoice emails and can't expose the checkout variables needed in JavaScript-Only Integration.
  2. You would like to carry out a customized integration with your existing rewards system.
  3. You have a non-standard checkout process for your online store (e.g. the invoice information is only finalized some time after the initial JavaScript tracking code is triggered)

Top tips when setting up your API Integration
Based on feedback from customers, here are the most important things to look out for when setting up the API integration to ensure that it'll work correctly
  1. Provide all of the required fields for a particular API method and include them in the signature calculation
    • If you provide non-required fields, make sure that they are also included as part of the signature calculation
  2. Sort all the name/value pairs in alphabetical order
    • If you have non-required fields, make sure to also sort them in alphabetical order
  3. 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 admin settings page

Worked example to calculate signature
Here's a worked example of how you would calculate the signature for the Purchase Method of the APIs.
  1. Gather all the field/value pairs that you have, ensuring that all the required fields have a value
    • List of fields used in this example to calculate signature
      • Required
        • ​first_name=ReferralCandy
        • email=example@referralcandy.com
        • order_timestamp=1464334498
        • browser_ip=
        • user_agent=Chrome
        • invoice_amount=100.0
        • currency_code=USD
        • timestamp=1464334600
      • Optional
        • last_name=Example
        • external_reference_id=1234
  2. Sort the field/value pairs in alphabetical order
    • Alphabetical list of fields
      2. browser_ip=
      3. currency_code=USD
      4. email=example@referralcandy.com
      5. external_reference_id=1234
      6. ​first_name=ReferralCandy
      7. invoice_amount=100.0
      8. last_name=Example
      9. order_timestamp=1464334498
      10. timestamp=1464334600
      11. user_agent=Chrome
  3. Join all of the field/value pairs into a single string​
  4. ​Prepend your API Secret Key to the single string from the previous step

  5. The calculated signature is the MD5 of the combined single string from the previous step
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found