Track with tolt.js

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

Your backendyour API

Toltplatform.tolt.com

1acme.com/?ref=sam → click

2tolt.signup()

3customer_id: cus_7Lm2…

4save cus_7Lm2… on the user

5POST /v2/transactions

6commission for Sam

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.

Script tag
Google Tag Manager

<script
  async
  src="https://files.tlt-cdn.com/v2/tlt.js"
  data-tolt="YOUR_PUBLIC_KEY"
></script>

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

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:

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.

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.

signup.js

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

Report every payment

Stripe, Paddle, Chargebee
Any other billing

Connect your billing provider in Dashboard → Settings → Integrations and follow its guide. Payments, renewals and refunds then flow in on their own.

Stripe

Paddle

Chargebee

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.

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",
});

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",
)

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.

Tolt pays the partner

Each transaction runs through your program’s commission flows. 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.

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.

Get started

Track conversions

Integrations

Concepts

Run your program

Guides

Track with tolt.js

Stripe

Paddle

Chargebee