TypeScript SDK

@tolt/api wraps every v2 endpoint in a typed method. Run it on your server: it needs your secret API key.

tolt.partners.list()GET /v2/partners Tolt

Returned

response200

successtrue

data[part_8fKq…, …]

has_moretrue

next_cursor

Thrown on 4xx, 5xx

ToltApiErrorNotFoundError

statusCode404

body.code

body.doc_url…/errors#not_found

Install

npm install @tolt/api

pnpm add @tolt/api

bun add @tolt/api

The package is ESM only. Get an API key in Dashboard → Settings → Integrations → Tolt API.

Initialize

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

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

Every method takes one request object, path params included ({ id: "part_..." }). Single-item calls return the API envelope { success, message, data }. list calls return a page you can iterate.

Common calls

List partners

for await walks every page. The SDK passes each next_cursor back as starting_after for you.

for await (const partner of await tolt.partners.list()) {
  console.log(partner.id, partner.email);
}

page.data holds one page’s rows, and page.response the envelope with has_more. Iteration only moves forward: with ending_before, read page.data and don’t iterate.

Create a customer

Bind a signup to a partner. customer_id is your id for the customer, ideally the one your billing system uses (a Stripe customer id, say), since billing integrations match payments on it. Send it or email. A partner_id (or link_id) is required; add the click_id tolt.js captured to keep the click’s link.

const { data: customer } = await tolt.customers.create({
  email: "jane@example.com",
  customer_id: "user_4821",
  partner_id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
  click_id: "clk_3hTq9WmZr2LxVb7nKcPd5sYe",
});
// customer.id is the Tolt id: cus_...

Record a payment

Amounts are integers in minor units (4900 = $49.00). Responses return money fields as strings ("4900") because they are stored as 64-bit integers. customer_id here is the Tolt cus_ id.

const { data: transaction } = await tolt.transactions.create({
  customer_id: customer.id,
  amount: 4900,
  billing_type: "subscription",
  interval: "month",
  charge_id: "ch_3PqR8sLmZx7RtYw3",
});

Refund it

await tolt.transactions.refund({ id: transaction.id });

Mint an embed token

For the partner dashboard embed. Pass a partner_id, or partner: { email, program_id }.

const { data } = await tolt.embedTokens.create({
  partner_id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
});
// data.token, data.expires_at

Errors

Non-2xx responses throw. Known statuses get their own class under the ToltApi namespace; everything else is a ToltApiError. ToltApiTimeoutError extends ToltApiError, so check it first.

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

try {
  await tolt.partners.get({ id: "part_8fKq2LmZx7RtYw3nVbHc5dPj" });
} catch (err) {
  if (err instanceof ToltApi.NotFoundError) {
    // err.body.code === "not_found"
  } else if (err instanceof ToltApiTimeoutError) {
    // no response within timeoutInSeconds
  } else if (err instanceof ToltApiError) {
    console.error(err.statusCode, err.body, err.requestId);
  } else {
    throw err;
  }
}

Class	Status
`ToltApi.BadRequestError`	400 (`validation_error`, `invalid_reference`, …)
`ToltApi.UnauthorizedError`	401
`ToltApi.NotFoundError`	404
`ToltApi.ConflictError`	409 (`already_exists`, `transaction_refunded`, …)
`ToltApi.TooManyRequestsError`	429
`ToltApiError`	Base class, and any other status

err.body is the error object (ToltApi.ErrorResponse): { success, message, code, doc_url, errors? }. err.requestId is the Request-Id to quote to support.

Retries and timeouts

Requests that fail with 408, 429 or 5xx are retried with exponential backoff, honoring Retry-After. Set defaults on the client, or override per call with a second argument.

const tolt = new ToltApiClient({
  token: process.env.TOLT_API_KEY!,
  maxRetries: 3,
  timeoutInSeconds: 30,
});

await tolt.partners.get({ id: "part_8fKq2LmZx7RtYw3nVbHc5dPj" }, { timeoutInSeconds: 5 });

Calls that create something (every create, and transactions.rerunFlows) are never retried, because a retry after a server error could create it twice. Before retrying one yourself, check whether it took effect. transactions.create with a charge_id is safe to retry: a duplicate fails with a 409 already_exists, so treat that as done.

Client option	Default
`token`	required	Your API key
`maxRetries`	`2`	Retries on 408, 429 and 5xx, except for creates
`timeoutInSeconds`	`60`	Per request
`headers`		Extra headers on every request
`baseUrl`	`https://platform.tolt.com`	API host
`fetch`	global `fetch`	Custom fetch implementation

Per-request options: maxRetries, timeoutInSeconds, abortSignal, headers, queryParams.

Response headers

Call .withRawResponse() to read headers such as X-RateLimit-Remaining or Request-Id.

const { data, rawResponse } = await tolt.partners.get({ id: "part_8fKq2LmZx7RtYw3nVbHc5dPj" }).withRawResponse();
console.log(rawResponse.headers.get("x-ratelimit-remaining"));

Resources

Resource	Methods
`partners`	`list` `get` `create` `update` `approve` `reject` `suspend` `bulkApprove` `bulkReject`
`customers`	`list` `get` `create` `update` `delete`
`transactions`	`list` `get` `create` `update` `delete` `refund` `rerunFlows`
`commissions`	`list` `get` `create` `update` `delete` `approve` `decline` `bulkApprove` `bulkDecline`
`links`	`list` `get` `getByParamValue` `create` `update` `delete`
`clicks`	`list` `get` `create`
`promotionCodes`	`list` `get` `create` `update` `delete`
`programs` `groups` `flows`	`list` `get`
`reports`	`overview` `partners` `links` `timeseries` `customers`
`embedTokens`	`create`

Each method maps to one endpoint in the API reference.

Overview

Server SDKs

Browser

Partner experiences

Tooling and AI

Install

Initialize

Common calls

List partners

Create a customer

Record a payment

Refund it

Mint an embed token

Errors

Retries and timeouts

Response headers

Resources

​Install

​Initialize

​Common calls

​List partners

​Create a customer

​Record a payment

​Refund it

​Mint an embed token

​Errors

​Retries and timeouts

​Response headers

​Resources

Install

Initialize

Common calls

List partners

Create a customer

Record a payment

Refund it

Mint an embed token

Errors

Retries and timeouts

Response headers

Resources