API Integration

Connect your store with ReferralCandy via API

Caye Arahan avatar
Written by Caye Arahan
Updated over a week ago

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:

  • You cannot BCC ReferralCandy on invoice emails, so Email Integration does not work for your store.

  • You cannot expose dynamic checkout variables needed for JavaScript Integration.

  • You want to do a custom integration with your existing rewards system.

  • You have a non-standard checkout process for your online store. For example, the invoice information is finalized some time after the initial JavaScript tracking code is triggered.

Integrating via API? View the ReferralCandy API Documentation.


Setting up API Integration

For API Integration, you will use the purchase method of the ReferralCandy API to send purchase information to ReferralCandy. You can also use other methods of our API to carry out a more customized integration with ReferralCandy.

Then, you'll have to insert the referral tracking code snippet on your store's purchase completed page.

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 their 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

      Generic

    • 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 on your Purchases & Referrals page or on the individual's profile page on your Existing Customers page.

403 Forbidden error

The API will return the HTTP 403 Forbidden error code when:

  • You haven't set a campaign to Live

  • Your campaign was stopped by the system

  • Your account is suspended

Please refer to our campaign states and account states articles to see how you can fix this issue.


Tips for ReferralCandy API Integration

  • Provide all of the required fields for a particular API method and include them in the signature calculation. See a sample

  • If you provide non-required fields, make sure that they are also included as part of the signature calculation

  • Sort all the name/value pairs in alphabetical order

  • If you have non-required fields, make sure to also sort them in alphabetical order

  • 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 My Profile page:

Worked example to calculate signature

Here's is 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 requiredfields have a value

    • List of fields used in this example to calculate signature

      • Required

        • first_name=ReferralCandy

        • order_timestamp=1464334498

        • browser_ip=173.255.155.102

        • user_agent=Chrome

        • invoice_amount=100.0

        • currency_code=USD

        • timestamp=1464334600

        • accessID=THISISMYACCESSID

      • Optional

        • last_name=Example

        • external_reference_id=1234

  2. Sort the field/value pairs in alphabetical order

    • Alphabetical list of fields

      1. accessID=THISISMYAPIACCESSID

      2. browser_ip=173.255.155.102

      3. currency_code=USD

      4. external_reference_id=1234

      5. first_name=ReferralCandy

      6. invoice_amount=100.0

      7. last_name=Example

      8. order_timestamp=1464334498

      9. timestamp=1464334600

      10. user_agent=Chrome

  3. Join all of 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

    Generic

  4. Prepend your API Secret Key to the single string from the previous step

    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

    Generic

  5. The calculated signature is the MD5 of the combined single string from the previous step

    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"

    Generic


πŸ’¬ Need help? Click the chat widget on the right to start a conversation. Learn more



​
​

Did this answer your question?