Pearl integration guide

Install one snippet, report one event per order. Conversions from creator affiliate links are attributed to the right creator automatically.

Overview

Pearl uses cookie-based last-touch attribution. When a shopper lands on your site via a creator link (?rwx=SLUG), the loader stores the creator slug in a first-party cookie for 30 days. When that shopper completes a purchase, you call Pearl.trackPurchase() with the order total and we credit the creator.

You install two things:

The loader <script> in your site's <head>.
A one-line Pearl.trackPurchase() call on your order confirmation / thank-you page.

Quick start

1. Grab your tracking key. Open Brand → Settings and copy the snippet (the key is filled in for you).
2. Install the loader. Paste it inside the <head> of every page on your site.
3. Report conversions. On your order confirmation page, call Pearl.trackPurchase({ value, currency, orderRef }).
4. Test it. Visit any creator's affiliate link, complete a test order, then check Brand → Dashboard for the conversion.

Loader reference

Replace YOUR_TRACKING_KEY with the value from your settings page. The endpoint is always https://african-creatorconnect.lovable.app/api/public/track/conversion — do not change it.

<!-- Pearl tracking — paste into <head> on every page -->
<script>
(function () {
  var KEY = "YOUR_TRACKING_KEY"; // from Brand → Settings
  var ENDPOINT = "https://african-creatorconnect.lovable.app/api/public/track/conversion";
  var COOKIE = "rwx_aff";
  var MAX_AGE = 60 * 60 * 24 * 30; // 30 days

  function setCookie(name, value) {
    document.cookie = name + "=" + encodeURIComponent(value)
      + "; Max-Age=" + MAX_AGE + "; Path=/; SameSite=Lax";
  }
  function getCookie(name) {
    var m = document.cookie.match(new RegExp("(?:^|; )" + name + "=([^;]*)"));
    return m ? decodeURIComponent(m[1]) : null;
  }

  try {
    var params = new URLSearchParams(window.location.search);
    var slug = params.get("rwx");
    if (slug && /^[a-z0-9]{3,32}$/.test(slug)) setCookie(COOKIE, slug);
  } catch (_) {}

  window.Pearl = {
    trackPurchase: function (opts) {
      var slug = getCookie(COOKIE);
      if (!slug || !opts || typeof opts.value !== "number") return;
      try {
        fetch(ENDPOINT, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          keepalive: true,
          body: JSON.stringify({
            trackingKey: KEY,
            slug: slug,
            value: opts.value,
            currency: opts.currency,
            orderRef: opts.orderRef,
          }),
        });
      } catch (_) {}
    },
  };
})();
</script>

Pearl.trackPurchase()

Call this once per completed order:

<script>
  Pearl.trackPurchase({
    value: 1299.00,        // final cart total in major units
    currency: "ZAR",       // optional, defaults to product currency
    orderRef: "ORDER-1234" // optional, prevents double counting
  });
</script>

Parameters

Name	Type	Required	Notes
value	number	Yes	Final cart total in major units (e.g. 1299.00 means R1,299, not cents).
currency	"ZAR" \| "NGN"	No	Defaults to the product's configured currency.
orderRef	string	No	Idempotency key (1–120 chars). The same orderRef will never be counted twice.

HTTP API

If you can't run JavaScript on your confirmation page (e.g. you only have a server-side webhook), post directly to the endpoint.

POST https://african-creatorconnect.lovable.app/api/public/track/conversion

curl -X POST https://african-creatorconnect.lovable.app/api/public/track/conversion \
  -H "Content-Type: application/json" \
  -d '{
    "trackingKey": "YOUR_TRACKING_KEY",
    "slug": "creator123",
    "value": 1299.00,
    "currency": "ZAR",
    "orderRef": "ORDER-1234"
  }'

Request body

trackingKey — UUID, your brand's tracking key.
slug — 3–32 lowercase alphanumerics, the creator's link slug.
value — number, order total in major units (max 100,000,000).
currency — optional, "ZAR" or "NGN".
orderRef — optional, 1–120 chars, idempotency key.

Responses

200 { ok: true } — recorded.
200 { ok: true, deduped: true } — same orderRef seen before.
200 { ok: true, skipped: "inactive" } — link is inactive or expired.
400 — invalid JSON or input.
401 — unknown tracking key.
403 — link does not belong to your brand.
404 — unknown link slug.

How attribution works

Creator links carry a ?rwx=SLUG query parameter. The loader captures it and stores it in a first-party cookie called rwx_aff.
The cookie is set SameSite=Lax and lives for 30 days. Last-touch wins — a newer click overwrites the cookie.
On purchase, the loader sends the cookie value with the order. If there's no cookie, no conversion is reported.
Conversions remain refundable during your configured return period (set in Brand → Settings). Only sales past the window are locked in for creator payout.

Platform recipes

Shopify (Customer Events pixel)

Install the loader in theme.liquid inside <head> so the rwx_aff cookie is set on the storefront. Then go to Settings → Customer events → Add custom pixel, paste the snippet below, set permissions to Not required, and click Save then Connect. The pixel fires once per completed checkout and reports the order to Pearl.

// Capture ?rwx=SLUG from the landing URL and persist it for checkout.
// The creator's link redirects through Pearl which appends ?rwx=SLUG to
// your product URL. We stash it in a first-party cookie on YOUR domain so
// it survives navigation to the checkout.
(function () {
  try {
    var url = new URL(window.top.location.href);
    var slug = url.searchParams.get("rwx");
    if (slug) {
      document.cookie =
        "rwx_aff=" + encodeURIComponent(slug) +
        "; path=/; max-age=2592000; samesite=lax; secure";
    }
  } catch (e) {}
})();

analytics.subscribe("checkout_completed", (event) => {
  const checkout = event.data.checkout;

  // Read the slug from the cookie we set on the storefront
  const m = document.cookie.match(/(?:^|; )rwx_aff=([^;]+)/);
  const slug = m ? decodeURIComponent(m[1]) : null;
  if (!slug) return; // no creator click → nothing to attribute

  fetch("https://african-creatorconnect.lovable.app/api/public/track/conversion", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      trackingKey: "YOUR_TRACKING_KEY",
      slug: slug,
      value: Number(checkout.totalPrice.amount),
      currency: checkout.totalPrice.currencyCode,
      orderRef: checkout.order.id,
    }),
  });
});

WooCommerce

Add the loader to your theme's header. Fire the purchase call from the woocommerce_thankyou hook in functions.php:

<?php
// functions.php — fires on the WooCommerce thank-you page
add_action('woocommerce_thankyou', function ($order_id) {
  $order = wc_get_order($order_id);
  ?>
  <script>
    Pearl.trackPurchase({
      value: <?php echo esc_js($order->get_total()); ?>,
      currency: "<?php echo esc_js($order->get_currency()); ?>",
      orderRef: "<?php echo esc_js($order->get_order_number()); ?>"
    });
  </script>
  <?php
});

Custom / SPA

Render the loader in your root HTML. After your checkout completes (success route, post-payment webhook handler, etc.), call window.Pearl.trackPurchase() with the order total.

Troubleshooting

No conversions appearing. Verify the tracking key matches your brand and the link slug belongs to one of your products (mismatched brand returns 403).
Cookie not set. The loader must run on the landing page where ?rwx=SLUG arrives. Server-side redirects that strip query params break attribution.
Values look 100× off. value is in major units, not cents. Pass 1299.00 not 129900.
Duplicate orders. Always pass orderRef. Repeat posts with the same orderRef are silently deduped.

Security & data

What we receive: tracking key, creator slug, order value, currency, and optional order reference.

What we never receive: customer name, email, address, payment details, or cart line items. Keep it that way — do not pass PII in orderRef.

The rwx_aff cookie is first-party, SameSite=Lax, and contains only the creator link slug.