This article applies if your store connects to ReferralCandy through the JavaScript Integration connection type. To compare connection types or find your platform's integration guide, see Integration overview.
The JavaScript integration works by adding a JavaScript code to your store's purchase completed page, which sends the customer's checkout information to ReferralCandy. This connection type detects purchases and referrals more accurately than email integration.
Before you begin integration
JavaScript integration requires experience in programming. If you're not a developer, consult one, or use email integration instead.
ReferralCandy doesn't provide troubleshooting support for custom code
Check that dynamic checkout variables — the order details your platform can print into the page, such as the customer's name, email, and order amount — are available on your eCommerce store's platform
Set up JavaScript integration
JavaScript integration involves adding a JavaScript code generated for your ReferralCandy account to your store's purchase completed page.
Step 1: Copy the JavaScript code
On your ReferralCandy dashboard, go to Integrations > Standalone.
If your connection type isn't JavaScript yet, click Change, select Javascript Integration, and click Save. This only switches which setup instructions the page shows — if another connection method is already running on your store (for example, invoice emails are being forwarded to ReferralCandy), remove it once the JavaScript integration is live, or ReferralCandy may record duplicate purchases.
In the Add ReferralCandy to your online store section, Copy the tracking code. The code is unique to your account, so always copy it from your own dashboard.
[📸 INSERT SCREENSHOT: Standalone tab with the JavaScript connection type active — the "Add ReferralCandy to your online store" panel showing the refcandy-mint tracking code, post-purchase checkbox unchecked]
Step 2: Add the code to your store page
Go to your store's admin panel.
Paste the code snippet before the closing
</body>tag on your purchase completed page.Replace the placeholder fields with the dynamic checkout variables from your store platform:
data-fname: Customer's first name
data-lname: Customer's last name
data-email: Customer's email address
data-amount: Invoice amount
data-currency: Invoice currency (3-letter code)
data-timestamp: Purchase timestamp (UNIX time format)
data-external-reference-id: Invoice number
data-signature: Calculated from the MD5 digest of a string containing the email address, first name, invoice amount, order timestamp, and secret key, in that order separated by commas. Ensure that this is done properly, otherwise it will result in a checksum error.
The snippet's script also supports optional attributes that are NOT in the pre-filled code — you won't see them in the div you copy. To use one, add it to the div yourself, and the script picks it up automatically:
data-accepts-marketing (optional): Whether the customer consented to receiving marketing emails ("true" or "false") — see "Obtain consent to receive marketing emails" below.
data-locale (optional): The customer's preferred language for ReferralCandy content, as an ISO 639-1 code. Defaults to your campaign's default language if not set or not available to the campaign. Valid values: en, fr, de, es, it, ja, nl, ru, zh-CN, zh-HK, zh-TW, da, no, sv, pt-BR.
Note: The MD5 signature is calculated based on the following: MD5(EMAIL,FIRST_NAME, INVOICE_AMOUNT,TIMESTAMP,ACCOUNT_SECRET)
Save the changes.
The JavaScript snippet contains two parts. The first one is an HTML div tag that contains invoice information, and the second part is a script element. The code snippet requires you to specify your API tokens.
To find your App ID and Secret Key, go to Account > Profile > API Tokens section — they're labeled API Access ID and API Secret ID there.
See a sample
See a sample
Here's a worked example for your reference:
App ID: THISISMYID
Secret Key: THISISMYKEY
If you have the following invoice:
Name: John Smith
Email: john@example.com
Invoice Amount: USD$10.20
Order timestamp (in UNIX time): 1396927808
In this example, the MD5 signature is: MD5("john@example.com,John,10.20,1396927808,THISISMYKEY") = eacb54f62a2d989bed54d02f4a171e94
The corresponding div element should be:
<div id="refcandy-mint" data-app-id="THISISMYID" data-fname="John" data-lname="Smith" data-email="john@example.com" data-amount="10.20" data-currency="USD" data-timestamp="1396927808" data-locale="en" data-signature="eacb54f62a2d989bed54d02f4a171e94"></div>
Show a post-purchase popup after checkout
The post-purchase popup shows qualified customers their referral link right after checkout — while your store is still front of mind — so they can start sharing immediately. On the JavaScript integration, the popup is part of the tracking code itself.
On the Integrations > Standalone page, check Show post-purchase widget after checkout.
Select which campaign the popup runs on from the Select campaign dropdown.
The tracking code updates — the snippet's div id switches from
refcandy-minttorefcandy-popsicle. Copy the updated code and use it on your purchase completed page in place of the standard version.
Note: If you're running multiple campaigns, the post-purchase popup can be enabled for one campaign at a time — the one selected on the Standalone page.
By default, the post-purchase popup shows the referral link to customers who qualify for your campaign. To let customers who don't qualify yet join too, go to Referral campaigns > your campaign > Widgets, and under Post-purchase popup, check Allow signup/waitlist for unqualified customers, then save your changes — those customers see a signup form instead, so they can join when they're ready. The popup looks like this:
Related: To customize the post-purchase popup's content and messaging, see Customizing your referral emails, pages, and widgets.
Obtain consent to receive marketing emails
Obtain consent to receive marketing emails
Always obtain consent from your customers before enrolling them in your referral program — for example, with a form input at checkout, unchecked by default, that says "I consent to receive notifications about your referral program."
Your checkout captures the customer's choice, and your tracking snippet relays it to ReferralCandy through the data-accepts-marketing attribute — set it to "true" or "false" based on what the customer actually chose, so ReferralCandy can flag the contact appropriately:
If the customer consented, they receive a referral email after purchase regardless of how they interact with the post-purchase popup.
If the customer didn't consent, they only receive a referral email if they click the "Share Invite Link" button in the popup.
If you'd like us to double-check that your setup is flagging consent correctly, just let us know.
Test the integration
To ensure purchases and referrals are detected accurately, verify that the JavaScript integration works with a test order.
First, make a test purchase at your store and look for these signs:
Does the purchase show up on the dashboard? Go to your Purchases & Referrals page and find the test order. If there's no purchase on the page, it means that the system can't detect purchases on your site.
Is the tracking code detected? On the Integrations > Standalone page, Last detected URL under the tracking code shows the page where the code was last seen — after your test purchase, it should show your purchase completed page's URL.
Are there checksum errors? On the same Standalone page, view the Debug Checksum Errors section. Check for errors to help you troubleshoot. If you don't see any transaction, it means that either the purchases are being detected correctly, or no purchase has been made.
Is something blocking the script? Cookie-consent tools, tag managers, and browser ad blockers can stop the tracking code from running. If the code is placed correctly but Last detected URL stays a dash (–) after a test purchase, check the browser console for blocked scripts.
