> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tolt.js

> Browser script reference: script attributes, the window.tolt API, tracking data, URL params and cookies.

tolt.js records a click when someone lands with a partner link, remembers it in a cookie, and binds the signup to that partner.

 acme.com/?ref=sam
click
 tolt.js
signup(email)
 Tolt

Saved as cookies

**tolt\_data**30 daysclick\_id"8537db0b…"partner\_id"part\_8fKq…"program\_id"prg\_2wXc…"customer\_idnull

Returned by signup()

**result**jane\@example.comcustomer\_id"cus\_7Lm2…"partner\_id"part\_8fKq…"click\_id"8537db0b…"program\_id"prg\_2wXc…"

## Install

```html theme={"system"}
<script
  async
  src="https://cdn.tolt.io/v2/tolt.js"
  data-tolt="YOUR_PUBLIC_KEY"
></script>
```

Add it to every page, as early in `<head>` as you can. Your public key is in **Dashboard → Settings → Integrations**; it is safe to ship to the browser. For framework setups, see [Install the script](/tracking/script).

> [!TIP]
>
> In a single-page app, load the script before your router runs. If the router rewrites the URL first, `?ref=sam` is gone before tolt.js can read it.

## Script attributes

| Attribute | |
| - | - |
| `data-tolt` | **Required.** Your public organization key. |
| `data-cookie-domain` | Cookie domain, e.g. `.acme.com`. By default tolt.js picks your root domain so `acme.com` and `app.acme.com` share the referral. |
| `data-stripe-type` | `payment_links`, `pricing_table` or `buy_button`. Passes the referral to Stripe as `client_reference_id`. See below. |
| `data-stripe-domain` | Your custom Stripe checkout domain (e.g. `https://pay.acme.com`), for `payment_links`. `buy.stripe.com` is always included. |

With `data-stripe-type`, tolt.js adds the click id to Stripe elements on the page, and keeps it there as the DOM changes:

* `payment_links`: appends `client_reference_id=<click_id>` to links pointing at Stripe.
* `pricing_table`: sets `client-reference-id` on `<stripe-pricing-table>`.
* `buy_button`: sets `client-reference-id` on `<stripe-buy-button>`.

## The window\.tolt API

| Member | Returns | |
| - | - | - |
| `tolt.ready()` | `Promise<ToltData \| null>` | Resolves once the script has initialized and the click (if any) is recorded. |
| `tolt.getTracking()` | `ToltData \| null` | Current referral data. Also available as the `tolt.tracking` getter. |
| `tolt.getReferral()` | `string \| null` | The click id of the current referral. Also `tolt.referral`. |
| `tolt.signup(identifier)` | `Promise<result>` | Binds the visitor to the partner as a customer. Alias: `tolt.identify(identifier)`. |
| `tolt.initialized` | `boolean` | `true` once the script has finished starting up. |

### Bind the signup

Call `signup()` after your own signup succeeds. It waits for the click to be recorded, and `?.` skips it if an ad blocker stopped the script. If your signup completes as the page loads, for example on an OAuth callback, check `window.tolt` first and wait for the `toltScriptLoaded` event if it isn't there yet.

```js theme={"system"}
async function onSignedUp(user) {
  const result = await window.tolt?.signup(user.email);
  if (result?.customer_id) {
    // store result.customer_id (cus_...) on your user
  }
}
```

Pass a stable identifier: the user's email or your own user id. To [record payments](/tracking/payments), use the Tolt id it returns (`result.customer_id`, `cus_...`), not that identifier.

> [!WARNING]
>
> `signup()` never throws. On a network error or after its 8 second timeout it resolves `undefined`; a duplicate call in flight resolves `{ message }`. Check `result?.customer_id` instead of wrapping it in `try`.

A successful result carries the new customer (plus a `message`):

```json theme={"system"}
{
  "customer_id": "cus_7Lm2Qx9RtVb3nKcPd5sYeHwJ",
  "customer_identifier": "jane@example.com",
  "click_id": "8537db0b-efeb-416c-ae68-07e6e2863a33",
  "partner_id": "part_8fKq2LmZx7RtYw3nVbHc5dPj",
  "program_id": "prg_2wXc4VnB8mQz6RtLp9KsYd3F"
}
```

## ToltData

`getTracking()` returns `null` when the visit did not come from a partner link. Otherwise every field can still be `null` until it is known.

**click\_id** `string | null`

The recorded click. Send it to `POST /v2/customers`, together with `partner_id`, if you bind customers from your server.

**partner\_id** `string | null`

The partner whose link was followed.

**program\_id** `string | null`

The program the link belongs to.

**cookie\_duration** `number | null`

Days the referral is remembered (your program's cookie window).

**customer\_id** `string | null`

Set after a successful `signup()`, so you can skip binding twice.

## Tracked URL params

tolt.js reads the first of these it finds in the query string (or the hash):

`tolt` `ref` `aff` `via` `lmref` `fpr` `tap_s` `afmc` `f2f-ref` `join` `ali`

The value must match a partner link in your program, e.g. `acme.com/?ref=sam` or `acme.com/pricing?via=sam`.

## Cookies

| Cookie | Holds |
| - | - |
| `tolt_referral` | The click id. |
| `tolt_data` | The `ToltData` object as URL-encoded JSON. |

Both last for the program's cookie window (30 days if unset), on the domain described above. On HTTPS they are set `Secure; SameSite=None`.

## Legacy globals

Older integrations can keep reading `window.tolt_referral` (click id) and `window.tolt_data` (`ToltData`). The script also fires a `toltScriptLoaded` event on `window` and `document` when it is ready; prefer `await tolt.ready()` in new code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.