Tracking snippet

The tracking snippet captures the affiliate referral (?ref=<slug>) in the
visitor's browser and stores it in a first-party cookie (ba_aff). Your backend
then reads that cookie value and passes it to the REST API as cookie_id (or
ref) when you report a customer or conversion. The snippet never sees or needs
your API key.

Install

Add the script to every page of your funnel, before </body>:

<script>
  (function(w,d,s,o){
    w.bee=w.bee||function(){(w.bee.q=w.bee.q||[]).push(arguments)};
    var j=d.createElement(s);j.async=true;
    j.src="https://script.partnerbee.app/beeaffiliate.js";
    d.head.appendChild(j);
  })(window,document,"script");

  bee('create', { integration: 'stripe' });
  bee('detect');
</script>

bee('detect') reads ?ref=<slug> from the URL, registers the click, and stores
the resulting tracking id in the ba_aff cookie (falling back to the raw slug if
the request is slow or fails). From then on the referral travels with the visitor
in that cookie.

What ba_aff holds: the click's cookie_id (or the link slug as a
fallback). You do not need to parse or interpret it. Read the cookie and pass its
value straight through as cookie_id to the REST API. PartnerBee resolves either
form.

The legacy host https://script.beeaffiliate.app/beeaffiliate.js remains
active. New sites should use script.partnerbee.app.

Snippet commands

bee('create', 'YOUR_ACCOUNT_ID', { integration: 'javascript' }); // configure
bee('detect');                                    // capture ?ref, set ba_aff cookie
bee('trial',      customerId, opts);              // sign-up (trial)
bee('customer',   customerId, opts);              // sign-up (customer)
bee('lead',       customerId, opts);              // sign-up (lead)
bee('conversion', conversionId, amount, opts);    // record a sale
// opts: { customer, meta, currency, coupon }

The sign-up and conversion commands read the ba_aff cookie automatically and
send it along, so you never pass the referral yourself, only your own ids
(customerId, conversionId). These are the client-side equivalent of
POST /api/customers and POST /api/conversions. Use them when you would rather
link the customer from the browser than from your backend (see
Full integration walkthrough).

Cookie scope (important)

The snippet sets ba_aff as a first-party cookie on the host where detect()
runs, with path=/. For the referral to survive from your landing page to your
signup or dashboard, that cookie must be readable there:

• Same host (landing and app on example.com): works out of the box.
• Different subdomains (example.com landing, app.example.com app): the
  cookie is not shared by default. Either serve ba_aff on the parent domain
  .example.com, or forward the referral in the signup URL (e.g.
  ?ref=<slug>) so it reaches the app, where detect() can re-capture it.
• Different domains entirely: forward the referral in the signup URL.

Content Security Policy

If your site sets a CSP, allow the PartnerBee host in script-src and
connect-src:

script-src 'self' https://*.partnerbee.app;
connect-src 'self' https://*.partnerbee.app;

Reading the referral on your backend

Read the ba_aff cookie at checkout and forward its value to the API:

const ref = req.cookies.ba_aff;           // set by the snippet
// ... later, when the sale completes:
await fetch('https://api.partnerbee.app/api/conversions', {
  method: 'POST',
  headers: {
    'Authorization': 'beeaff-<your-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ cookie_id: ref, external_id: orderId, amount: 199.90 }),
});

If you use a payment provider, you can skip this call and let a
webhook report the sale instead. Store ref in the provider's
customer or checkout metadata so the webhook can attribute it.