Skip to main content

[Other Platforms] API integration guide

Connect your store to ReferralCandy through the API — setup steps, tracking code, other API methods, and common errors.

Written by Adam

This article applies if your store connects to ReferralCandy through the API Integration connection type — your systems send purchase information to ReferralCandy through the ReferralCandy API. To compare connection types or find your platform's integration guide, see Integration overview.

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

The API integration is the right connection type when:

  • 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.

  • Your storefront or checkout is headless or fully custom, so there's no standard purchase completed page for the other connection types to hook into.

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 Referral campaigns > Select your campaign. The join page URL is at the top of the campaign page, next to Promote your 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. If your connection type isn't API yet, click Change, select API Integration, and click Save. This only switches which setup instructions the page shows — if another connection method is already running on your store, remove it once the API integration is live, or ReferralCandy may record duplicate purchases.

  3. Before wiring your purchase flow, test your setup with the verify method — a successful response confirms your authentication credentials and signature calculation are correct.

  4. 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/v2.2/purchase.json

    • If a discount code was used on the order, the discount_code field is required — and friend offer codes help ReferralCandy attribute the referral to the right advocate

    • The optional accepts_marketing field records whether the customer consented to receiving marketing emails — it defaults to true if not sent

    • The optional referrer_id field is a recommended upgrade: it directly identifies the referring advocate for the purchase. By default, ReferralCandy detects referrals by matching signals — the referral-link visit, browser IP, and user agent — while referrer_id gives it an explicit answer for who referred the purchase. Usually this is the aic parameter ReferralCandy appends to your store URL when a friend arrives through a referral link: capture it when the friend lands on your store and include it with the purchase.

  5. Make a test purchase at your store.

  6. 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.

Step 2: Add the referral tracking code to your store

  1. On the ReferralCandy dashboard, go to Integrations > Standalone. The tracking code is in the Add ReferralCandy to your online store section — click Next on the listening step if it isn't visible yet.

  2. Copy the code snippet. The code is unique to your account, so always copy it from your own dashboard.

  3. Paste the code just before the closing </body> tag on your store's purchase completed page.

For the full walkthrough of this step — including how to confirm the code is being detected — see Adding the referral tracking code.

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 Account > Profile — your API tokens (API Access ID and API Secret ID) are in the API Tokens section.

Beyond purchases: other API methods

The purchase method covers the core store connection, but the ReferralCandy API also has methods for managing contacts, referrals, and rewards programmatically:

  • Verify — test that your authentication credentials and signature calculation are set up correctly

  • Campaigns — list the campaigns on your account

  • Signup — enroll a contact in your campaigns programmatically; the response includes the advocate's referral link and portal sharing page

  • Invite — send the welcome email to a contact enrolled in a campaign

  • Referral — update the status of a referred purchase, for example to report a return so the advocate isn't rewarded for it

  • Referrals, Referrer, and Contacts — query referred purchases, look up who referred a particular customer, and list your contacts

  • Unsubscribed — unsubscribe or resubscribe a contact from your referral program emails

  • Rewards methods — query and update custom rewards, used when accumulating referral rewards in your own platform

See the API Documentation for each method's parameters, responses, and examples.

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. You can also confirm the tracking code itself is being seen: on the Standalone page, Last detected URL under the tracking code shows the page where the code was last detected.

A purchase can be recorded without being marked as a referral. If that's what you see, the usual causes are qualification rather than the integration — the friend used the same browser or IP address as the advocate, the order was below the minimum purchase amount, or the purchase is still in the review period. See Troubleshooting referral detection.

Common API errors

The ReferralCandy API responds with standard HTTP status codes. The three you're most likely to see while integrating:

  • 401 Unauthorized — your authentication credentials are incorrect. Check your API Access ID and API Secret ID (Account > Profile > API Tokens). Note that Reset API Secret on that page invalidates the old key immediately — if the secret was recently reset, update your integration with the new value.

  • 400 Bad Request — something in the request is wrong; the response's message field says what. Common causes: an invalid signature (fields not sorted alphabetically, or fields sent but left out of the signature calculation), a timestamp format issue, or an invalid email, currency code, or amount.

  • 403 Forbidden — authentication worked, but the method isn't available right now. The API returns this when your campaign isn't live, your campaign was stopped by the system, or your account is suspended — the response's message and reason fields have details. Refer to the campaign states and account states articles to learn how to fix issues related to this error.

Note: Send each order once — a purchase re-sent with the same external_reference_id is deduplicated rather than recorded twice. If a purchase seems missing, check whether it was already sent before sending it again.

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

      • Optional

        • last_name=Example

        • external_reference_id=1234

  2. Sort the field and value pairs in alphabetical order.

    • Alphabetical list of fields

      1. accessID=THISISMYACCESSID

      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=1581002448

      10. timestamp=1581062448

      11. user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:72.0) Gecko/20100101 Firefox/72.0

  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

  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

  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"
Related Articles
Did this answer your question?