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

# TypeScript SDK

> @tolt/api: a typed client for the Tolt API, with retries, timeouts and typed errors.

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

![](https://mintcdn.com/tolt-29/IdZ6_r2VYMOh5a6x/images/logos/typescript.svg?fit=max\&auto=format\&n=IdZ6_r2VYMOh5a6x\&q=85\&s=247db6e066d0e84e71dc73e7ba460b8b) tolt.partners.list()
GET /v2/partners
 Tolt

Returned

**response**200successtruedata\[part\_8fKq…, …]has\_moretruenext\_cursor"cur\_WyIy…"

Thrown on 4xx, 5xx

**ToltApiError**NotFoundErrorstatusCode404body.code"not\_found"body.doc\_url…/errors#not\_found

## Install

```bash npm theme={"system"}
npm install @tolt/api
```

```bash pnpm theme={"system"}
pnpm add @tolt/api
```

```bash bun theme={"system"}
bun add @tolt/api
```

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

## Initialize

```ts theme={"system"}
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.

```ts theme={"system"}
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.

```ts theme={"system"}
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.

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

### Refund it

```ts theme={"system"}
await tolt.transactions.refund({ id: transaction.id });
```

### Mint an embed token

For the [partner dashboard embed](/sdks/embed). Pass a `partner_id`, or `partner: { email, program_id }`.

```ts theme={"system"}
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.

```ts theme={"system"}
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](/api-reference/errors) (`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.

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

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

> [!WARNING]
>
> 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`.

```ts theme={"system"}
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](/api-reference/introduction).


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