Track without tolt.js

The same flow as with tolt.js, done with three API calls from your backend. Use it when the script can’t run: mobile apps, links you redirect yourself, or sales-led deals.

Visitorsite or app

Your backendyour API

Toltplatform.tolt.com

1GET /?ref=sam

2POST /v2/clicks

3clk_3nVb… part_8fKq…

5POST /v2/customers

6cus_Q7wR…

7POST /v2/transactions

8commission for Sam

All three calls use an API key from Dashboard → Settings → Integrations → Tolt API, sent as Authorization: Bearer.

Record the click when a visitor lands

When a request arrives with your program’s link parameter (?ref=sam), record the click and keep the returned ids with the visitor, in a cookie or on the anonymous session, for your program’s cookie window (the Cookie duration in your program settings). A failed call only loses that click; the page still loads.

landing.ts

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

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });
const COOKIE_WINDOW_DAYS = 30; // your program's cookie duration

export function readClick(raw: string | undefined): { id: string; partner_id: string } | null {
  try {
    const click = JSON.parse(raw ?? "");
    return typeof click?.id === "string" && typeof click?.partner_id === "string" ? click : null;
  } catch {
    return null; // a malformed cookie just means no referral
  }
}

app.use(async (req, res, next) => {
  const ref = req.query.ref;
  if (typeof ref === "string" && !readClick(req.cookies.tolt_click)) {
    try {
      const { data: click } = await tolt.clicks.create(
        { param: "ref", value: ref, page: `https://acme.com${req.originalUrl}` },
        { timeoutInSeconds: 2, maxRetries: 0 }, // never hold the page for long
      );
      res.cookie("tolt_click", JSON.stringify({ id: click.id, partner_id: click.partner_id }), {
        maxAge: COOKIE_WINDOW_DAYS * 24 * 60 * 60 * 1000,
        httpOnly: true,
      });
    } catch (error) {
      // An unknown ?ref= value is not a referral. Anything else (timeout, outage)
      // loses this click but must not take the page down.
      if (!(error instanceof ToltApi.BadRequestError)) console.error("Tolt click failed", error);
    }
  }
  next();
});

A value that matches no partner link returns 400 invalid_reference, so a mistyped ?ref= never creates anything. Optional fields: referrer, country (ISO 2) and device. In a mobile app, call the same endpoint from your backend when the app opens from a partner’s deep link.

Create the customer at signup

After your own signup succeeds, bind the user to the partner. partner_id is required; click_id ties the signup to that exact click. Pass your own user id as customer_id so you can look the customer up later. Treat it as best effort: the account exists either way, so a Tolt error shouldn’t fail the signup.

// Returns the Tolt customer id (cus_...). Safe to run again from a retry job.
async function bindCustomer(user: { id: string; email: string }, click: { id: string; partner_id: string }) {
  try {
    const { data: customer } = await tolt.customers.create(
      { email: user.email, customer_id: user.id, partner_id: click.partner_id, click_id: click.id },
      { timeoutInSeconds: 5 },
    );
    return customer.id;
  } catch (error) {
    // The create may have gone through even if this call failed (a timeout, or an
    // earlier attempt): look the customer up by your own user id.
    const found = await tolt.customers.list({ customer_id: user.id, limit: 1 }).catch(() => null);
    if (found?.data[0]) return found.data[0].id;
    console.error("Tolt customer failed", error); // queue a retry
    return null;
  }
}

const click = readClick(req.cookies.tolt_click); // from step 1
if (click) {
  const toltCustomerId = await bindCustomer(user, click);
  if (toltCustomerId) await saveToltCustomerId(user.id, toltCustomerId);
}

customer = client.customers.create(
    email=user.email,
    customer_id=user.id,
    partner_id=click["partner_id"],
    click_id=click["id"],
).data
save_tolt_customer_id(user.id, customer.id)  # cus_...

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": "clk_3nVbHc5dPj8fKq2LmZx7RtYw"
  }'

No click at all, like a deal a partner closed over email? Create the customer with the partner’s partner_id and leave out click_id.

Report every payment

On each successful charge, renewals included, send the cus_... id you saved. Amounts are in the smallest unit of your program’s currency (cents for USD). If you bill through Stripe, Paddle or Chargebee, you can connect the integration instead.

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

client.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_Q7wRt2YxLm9KfZ3nPb8HcV4d",
    "amount": 4900,
    "charge_id": "ch_3Qf8x2aBcD",
    "product_name": "Pro plan",
    "billing_type": "subscription",
    "interval": "month"
  }'

A retry with the same charge_id 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, sign up, and pay. The click, the customer and the commission show up under that partner within seconds.

Get started

Track conversions

Integrations

Concepts

Run your program

Guides

Track without tolt.js