Skip to main content

API Integration

Connect your store with ReferralCandy via API

Adam avatar
Written by Adam
Updated over 2 months ago

The API integration allows you to connect your store to ReferralCandy with greater control and customization options for implementing a referral or affiliate program.

Why API integration

  • You can't BCC ReferralCandy on invoice emails, so email integration doesn't work for your store

  • You can't expose dynamic checkout variables needed for the 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 sometime after the initial JavaScript tracking code is triggered.

Refer to the ReferralCandy API Documentation.

How API Integration works

  1. A referrer signs up by visiting your join page URL. To find this link, on the ReferralCandy dashboard go to Campaigns > Select your campaign > Emails & Pages. Find the join page URL next to Promote your referral program.

  2. If the customer meets your segment criteria, they are enrolled in your campaign and see their unique referral 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.

  5. You should see referrals detected on your Purchases & Referrals page.

How do campaigns work? See the referral campaign map to learn more.

Set up API Integration

Step 1: Use the purchase method

Connect your store to ReferralCandy using the purchase method.

  1. On the ReferralCandy dashboard, go to Integrations > Standalone.

  2. Choose API Integration as the connection type and click Next.

  3. Use the purchase method to send purchase information from your store to ReferralCandy, 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. See how it works

      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

  4. Make a test purchase at your store.

  5. In the Listening for API request. Make a purchase to send us a signal section, click Next. If you correctly set up the purchase method, this section shows a green checkmark.

You can also use other ReferralCandy API methods to implement a more customized store integration with ReferralCandy.

Step 2: Add the referral tracking code to your store

  1. On the ReferralCandy dashboard, go to Integrations > Standalone.

  2. Copy the code snippet provided.

  3. Add the referral tracking code snippet to your store's purchase completed page. Paste the code just before the </body> tag.

Tips for ReferralCandy API integration

  • Provide all 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 and value pairs in alphabetical order

  • If you have non-required fields, sort them in alphabetical order

  • Use the correct values for the access ID and secret key. On the ReferralCandy dashboard, go to Profile to find your API tokens.

Testing and troubleshooting

To ensure that the referral tracking code works, make a test purchase in your store and go to your Purchases & Referrals page to verify that purchases are detected.

403 Forbidden error

The API returns the HTTP 403 Forbidden error code when:

  • Your campaign isn't live

  • Your campaign was stopped by the system

  • Your account is suspended

Refer to the campaign states and account states articles to learn how to fix issues related to this error.


Sample signature

Worked example to calculate signature

Here's how you'd calculate the signature for the purchase method.

  1. Gather all the field and value pairs 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=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 and value pairs in alphabetical order.

    • Alphabetical list of fields

      1. accessID=THISISMYAPIACCESSID

      2. browser_ip=173.255.155.102

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

Related Articles
Email integration and API integration: Adding the referral tracking code
Integration overview
Integration: Squarespace
JavaScript integration
Integration: Magento 2
Did this answer your question?