> ## 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.

# Track with tolt.js

> The full flow: tolt.js records the click, tolt.signup() turns the visitor into a customer, and your backend reports each payment.

From a partner's link to their commission, end to end. The browser script handles the click and the signup; your backend only reports payments.

Browsertolt.jsYour backendyour APIToltplatform.tolt.com*1*acme.com/?ref=sam → click*2*tolt.signup("jane\@example.com")*3*customer\_id: cus\_7Lm2…*4*save cus\_7Lm2… on the user*5*POST /v2/transactions*6*commission for Sam

**1. Add the script**

Paste this in the `<head>` of every page, on your marketing site and in your app. Your public key is in **Dashboard → Settings → Integrations → Tolt API**.

> [tab] Script tag
>
> ```html theme={"system"}
> <script
>   async
>   src="https://files.tlt-cdn.com/v2/tlt.js"
>   data-tolt="YOUR_PUBLIC_KEY"
> ></script>
> ```

> [tab] Google Tag Manager
>
> ```html theme={"system"}
> <script>
>   var toltScript = document.createElement("script");
>   toltScript.src = "https://files.tlt-cdn.com/v2/tlt.js";
>   toltScript.setAttribute("data-tolt", "YOUR_PUBLIC_KEY");
>   document.head.appendChild(toltScript);
> </script>
> ```

Framework setups (Next.js, React, Vue, Webflow, WordPress) are in [Install tolt.js](https://docs.tolt.com/tracking/script.md).

**2. The click is recorded for you**

When someone lands through a partner link like `acme.com/?ref=sam`, the script records the click and remembers the partner in a first-party cookie for your program's cookie window. Nothing to call. To check it, open a partner link and run this in the console:

```js theme={"system"}
await tolt.ready();
// {
//   click_id: "8537db0b-efeb-416c-ae68-07e6e2863a33",
//   partner_id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
//   program_id: "prg_2wXc4VnB8mQz6RtLp9KsYd3F",
//   cookie_duration: 30,
//   customer_id: null,
// }
```

`customer_id` stays `null` until the signup in the next step.

**3. Call tolt.signup() when they sign up**

Right after your own signup succeeds, pass the user's email (or your own user id). Tolt turns the click into a customer that belongs to Sam, for good. Visitors who didn't come through a partner link are ignored, so call it for everyone.

```js signup.js theme={"system"}
async function onSignedUp(user) {
  const result = await window.tolt?.signup(user.email);

  if (result?.customer_id) {
    // Save it on your user. Payments are reported with this id.
    await fetch("/api/tolt-customer", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ toltCustomerId: result.customer_id }),
    });
  }
}
```

`signup()` waits for the click to be recorded, and `?.` skips the call if an ad blocker stopped the script. If the signup finishes while the page is still loading, for example on an OAuth callback, check `window.tolt` first and wait for the `toltScriptLoaded` event if it isn't there yet.

| Store on your user | Example | Used for |
| - | - | - |
| `customer_id` | `cus_7Lm2Qx9RtVb3nKcPd5sYeHwJ` | Every payment you report in the next step |
| `partner_id` (optional) | `part_8fKq2LmZx7RtYw3nVbHc5dPj` | Showing "referred by" in your own admin |

**4. Report every payment**

> [tab] Stripe, Paddle, Chargebee
>
> Connect your billing provider in **Dashboard → Settings → Integrations** and follow its guide. Payments, renewals and refunds then flow in on their own.
>
> > [card] [Stripe](https://docs.tolt.com/integrations/stripe.md)
>
> > [card] [Paddle](https://docs.tolt.com/integrations/paddle.md)
>
> > [card] [Chargebee](https://docs.tolt.com/integrations/chargebee.md)

> [tab] Any other billing
>
> From your backend, report each successful charge, renewals included, with the `customer_id` you saved. Amounts are in the smallest unit of your program's currency (cents for USD). Use an API key from **Dashboard → Settings → Integrations → Tolt API**.
>
> ```ts TypeScript theme={"system"}
> import { ToltApiClient } from "@tolt/api";
>
> const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });
>
> await tolt.transactions.create({
>   customer_id: user.toltCustomerId,
>   amount: 4900, // $49.00
>   charge_id: charge.id,
>   product_name: "Pro plan",
>   billing_type: "subscription",
>   interval: "month",
> });
> ```
>
> ```python Python theme={"system"}
> import os
> from tolt import ToltApi
>
> tolt = ToltApi(token=os.environ["TOLT_API_KEY"])
>
> tolt.transactions.create(
>     customer_id=user.tolt_customer_id,
>     amount=4900,  # $49.00
>     charge_id=charge.id,
>     product_name="Pro plan",
>     billing_type="subscription",
>     interval="month",
> )
> ```
>
> ```bash cURL theme={"system"}
> curl -X POST https://platform.tolt.com/v2/transactions \
>   -H "Authorization: Bearer $TOLT_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "customer_id": "cus_7Lm2Qx9RtVb3nKcPd5sYeHwJ",
>     "amount": 4900,
>     "charge_id": "ch_3Qf8x2aBcD",
>     "product_name": "Pro plan",
>     "billing_type": "subscription",
>     "interval": "month"
>   }'
> ```
>
> `charge_id` is your billing system's id for the charge. A retry with the same one returns `409 already_exists` instead of booking the payment twice. Refund with the returned `txn_...` id, see [Record payments](https://docs.tolt.com/tracking/payments.md#refunds).

**5. Tolt pays the partner**

Each transaction runs through your program's [commission flows](https://docs.tolt.com/concepts/commission-flows.md). When the conditions match, Sam gets a commission, which is approved (right away or after your approval window) and then paid out with the next payout run.

Test it end to end: create a test partner, open their link in a private window, sign up, and pay. The customer and the commission show up under that partner within seconds.

> [!TIP]
>
> No browser on the path, like a mobile app or a sales-led deal? Do the same three steps from your server: [Track without tolt.js](https://docs.tolt.com/guides/without-toltjs.md).


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