Track signups

When a referred visitor creates an account, tell Tolt once. Tolt links the click cookie to a new customer and binds that customer to the partner.

tolt.jstolt.signup(email) Tolt

Created in Tolt

customercus_3VbH…

partner

statuslead

Returned to your app

result

customer_idcus_3VbH…

partner_idpart_8fKq…

click_id8537db0b…

program_idprg_YxLm…

Bind once, every renewal pays. Jane’s later payments keep crediting Sam.

Browser
Server

Call tolt.signup() right after your own signup succeeds. Pass the user’s email (or your user id). It resolves with Tolt’s customer id, cus_.... 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.

const result = await window.tolt?.signup(user.email);

if (result?.customer_id) {
  // Save it on your user. You'll need it to record payments.
  await saveToltCustomerId(user.id, result.customer_id);
}

tolt.signup() never throws. Visitors without a referral, or a repeat signup, resolve without a customer_id, so always check result?.customer_id.With @tolt/tracking, for example in React, wait for init() first:

import { init, signup } from "@tolt/tracking";

// Call after your own signup succeeds. init() resolves once
// tolt.js has loaded, and does nothing after the first call.
async function trackSignup(user: { id: string; email: string }) {
  await init({ publicKey: "YOUR_PUBLIC_KEY" });
  const result = await signup(user.email);
  if (result?.customer_id) {
    await saveToltCustomerId(user.id, result.customer_id);
  }
}

Create the customer from your backend. First send the tracking data from the browser along with your signup request:

// null when the visitor wasn't referred
const tracking = (await window.tolt?.ready()) ?? null;

await fetch("/api/signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password, tolt: tracking }),
});

Then, if tolt.partner_id is set, create the customer with your API key:

import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

const { data: customer } = await tolt.customers.create({
  email: "jane@example.com",
  customer_id: "user_1042", // your own user id
  partner_id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
  click_id: "8537db0b-efeb-416c-ae68-07e6e2863a33",
});
// Save customer.id (cus_...) on your user

import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

res = client.customers.create(
    email="jane@example.com",
    customer_id="user_1042",  # your own user id
    partner_id="part_8fKq2LmZx7RtYw3nVbHc5dPj",
    click_id="8537db0b-efeb-416c-ae68-07e6e2863a33",
)
# Save res.data.id (cus_...) on your user

curl -X POST https://platform.tolt.com/v2/customers \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "customer_id": "user_1042",
    "partner_id": "part_8fKq2LmZx7RtYw3nVbHc5dPj",
    "click_id": "8537db0b-efeb-416c-ae68-07e6e2863a33"
  }'

partner_id (or link_id) is required. click_id is optional and must belong to that partner. A duplicate email returns 409 already_exists.

What gets created

idTolt’s customer id (cus_…). Use it as customer_id on transactions.partner_idSam. Fixed from now on.statuslead until the first payment, then active.customer_idYour own id, only when you set it via the API.

Get started

Track conversions

Integrations

Concepts

Run your program

Guides

What gets created

​What gets created

What gets created