Quick Start: JavaScript

Add referral tracking to any website — Shopify, Squarespace, custom builds, or anything with a checkout. No server-side code required.

Prerequisites

An AdvocateLoop account (sign up here)
Access to edit your site’s HTML (directly or via a tag manager like Google Tag Manager)

Step 1: Add the tracking script

Add this script tag to every page on your site, ideally in the <head> or just before </body>. Replace the Brand ID with yours from the AdvocateLoop dashboard (Settings → API Keys).

<script src="https://api.advocateloop.com/al.js?brand=YOUR-BRAND-UUID"></script>

Using Google Tag Manager

If you use GTM, create a Custom HTML tag with the script above and set it to fire on All Pages. No additional configuration is needed — the brand ID is embedded in the script URL.

The widget lets visitors claim referral discounts and lets customers sign up as advocates. Add an empty div wherever you want the widget to appear:

<div data-al-widget></div>

That’s it. The full widget UI will automatically be detected and will load.

Step 3: Track conversions

After a customer completes a purchase, record the conversion. Fire the following to your thank-you or order confirmation page:

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function() {
    AdvocateLoop.trackConversion({
      order_id: 'ORD-12345',         // Your unique order ID
      order_total: 108.00,            // What the customer paid (everything in)
      tax: 8.00,                      // Total tax (use 0 if not applicable)
      shipping: 10.00,                // Total shipping (use 0 if not applicable)
      discount: 5.00,                 // Total discount (use 0 if no coupon)
      customer_email: 'buyer@example.com',
      items: [                        // Optional: line items in the order
        {
          name: 'Vitamin C Serum',
          quantity: 2,
          unit_price: 32.00,
          sku: 'VITC-30',
          category_path: ['Skincare', 'Serums']
        },
        { name: 'Gift Wrapping', quantity: 1, unit_price: 4.00 }
      ]
    });
  });
</script>

Dynamic order data

Most platforms provide order data on the thank-you page via template variables. Here are examples for common platforms:

Shopify:

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function() {
    AdvocateLoop.trackConversion({
      order_id: '{{ order.order_number }}',
      order_total: {{ order.total_price | money_without_currency }},
      tax: {{ order.tax_price | money_without_currency }},
      shipping: {{ order.shipping_price | money_without_currency }},
      discount: {{ order.total_discount | money_without_currency }},
      customer_email: '{{ order.email }}'
    });
  });
</script>

Squarespace (via code injection on order confirmation):

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function() {
    AdvocateLoop.trackConversion({
      order_id: '{orderId}',
      order_total: {orderGrandTotal},
      tax: {orderTaxTotal},
      shipping: {orderShippingTotal},
      discount: {orderDiscountTotal},
      customer_email: '{customerEmailAddress}'
    });
  });
</script>

Note for Squarespace: Variable names vary across Squarespace plans and template versions. If a variable isn’t available in your plan, use 0 as a placeholder for that field.

Conversion parameters

Parameter	Type	Required	Description
`order_id`	string	Yes	Unique order identifier
`order_total`	number	Yes	What the customer paid (everything in: items + tax + shipping − discounts)
`tax`	number	Yes	Total tax. Use `0` if not applicable
`shipping`	number	Yes	Total shipping. Use `0` if not applicable
`discount`	number	Yes	Total discount applied. Use `0` if no coupon
`customer_email`	string	Yes	Customer’s email address
`customer_name`	string	No	Customer’s name
`items`	array	No	Line items in the order. Fields below.

Each entry in items:

Field	Type	Required	Description
`name`	string	Yes	Item or service name
`quantity`	number	No	Units. Defaults to `1`
`unit_price`	number	No	Price per unit. Or send `line_total` for the line’s total
`sku`	string	No	SKU, plan code, or service code
`category_path`	array	No	Ordered category path, top level first — e.g. `['Skincare', 'Serums']`
`image_url`	string	No	Image URL for the item

Most platforms expose line items on the order-confirmation page; map each line into one entry in the array.

Step 4: Configure your referral program

In the AdvocateLoop dashboard:

Go to Configure → Rewards
Set your customer discount (e.g., 15% off or $10 off)
Set your advocate reward (e.g., $10 credit per referral)
Set your attribution window (how long referral links stay valid)

Step 5: Test it

Create a test advocate in the dashboard and note their referral code
Open an incognito window and visit your site with the referral link:
```
https://yoursite.com/?ref=V2AVMRDJ
```
Open the browser console — you should see [AdvocateLoop] log messages confirming the click was tracked
Complete a test purchase — check the dashboard for the conversion

About the queue pattern

The AdvocateLoopQueue pattern shown in Step 3 ensures the conversion is tracked even if your code runs before the base script finishes loading. Wrap any call to the AdvocateLoop global in a queue function and the call will execute as soon as the script is ready.

Applying discounts

AdvocateLoop tracks referrals and attributes conversions, but applying the actual discount depends on your platform:

Shopify — Create a discount code matching the referral code, or use Shopify Scripts
Squarespace — Use promo codes in Commerce settings
Custom checkout — Apply the discount in your backend when a referral code is present

Next steps

JavaScript SDK — full reference for the browser SDK: the queue pattern, trackConversion, and widget events
Widgets — placing, customizing, and the hosted brand page
REST API — record events from your server instead of the browser