---
description: "Connect Tolt to Plandalf, pass Tolt referral IDs into checkout, and record a Tolt transaction for every paid invoice an affiliate referred."
---
# Tolt setup

Keep running your affiliate program in Tolt while Plandalf takes the payments. When an affiliate-referred buyer pays, a sequence registers the customer with the referring partner in Tolt and records the sale with each product on the invoice, so Tolt can work out the commission.

Setup has three parts: connect your Tolt account, pass Tolt’s referral IDs into checkout from your website, and add the paid-invoice sequence.

> [!WARNING]
> **What it covers today**
> The Tolt steps record first sales. Every transaction is sent as a one-time payment, renewals without the original referral details are skipped, and there is no refund step. Handle renewals and refunds in Tolt.

## Before you start

-   A Tolt account with an affiliate program, and Tolt’s tracking script on your website.
-   Plandalf checkouts whose products are linked to Stripe products. Tolt needs a Stripe product ID (`prod_…`) for each item it records.
-   Your organization’s Plandalf SDK on the pages that open checkout.

## Get your Tolt details

Plandalf asks for up to three values from Tolt:

-   **API Key**: in Tolt, go to **Settings → Integrations** and create an API key. Use this secret key, not the public `pk_…` key in your website script.
-   **Program ID**: starts with `prg_`. Open your program in Tolt and copy it from the address bar, or type `window.tolt_data.program_id` in the browser console on a page where Tolt’s script runs.
-   **Own partner id** (optional): starts with `part_`. If you send your own newsletter traffic through a Tolt partner link, find that partner in **Tolt → Partners** and copy its ID. Plandalf then labels those visits as direct instead of affiliate traffic.

## Connect Tolt to Plandalf

1.  [Find Tolt in the Marketplace](#find-tolt-in-marketplace)

    In Plandalf, open **Automation** in the sidebar and choose the **Marketplace** tab. Find **Tolt** under **Available now** and click **Connect**.

2.  [Enter your details](#enter-tolt-details)

    In the **Connect Tolt** window, keep or change the **Integration name**. Paste the **API Key** and **Program ID**, add your **Own partner id** if you have one, then click **Connect**.

Tolt has no way to check a key in advance, so the connection always saves. A wrong key shows up as an authorization error the first time a Tolt step runs, which is why the example below ends with a test.

## Pass Tolt’s referral IDs into checkout

Tolt’s script knows which affiliate sent the visitor. Plandalf needs those IDs saved on the checkout so the paid-invoice sequence can read them. Add this configuration once, on every page that opens a Plandalf checkout, after Tolt’s script and the Plandalf SDK:

```html
<script>
  plandalf("configure", {
    properties: {
      tolt_click_id: () => window.tolt_data?.click_id || window.tolt_referral || null,
      tolt_partner_id: () => window.tolt_data?.partner_id || null,
      tolt_program_id: () => window.tolt_data?.program_id || null
    }
  });
</script>
```

Each value is read when the checkout opens, so it still works if Tolt’s script loads a moment after Plandalf’s. The sequence then sees them as `{{trigger.session_properties.tolt_click_id}}` and `{{trigger.session_properties.tolt_partner_id}}`. For Stripe customer metadata, WordPress and other setups, see [Tolt with Plandalf checkout](https://plandalf.com/docs/product-guides/platforms/tolt).

## Steps you can add

### Find or Create Customer

Registers the buyer in Tolt against the referring partner. If no partner ID reached the checkout, the step is skipped, because there is nothing to credit.

-   **Email** (required): `{{trigger.customer_email}}`.
-   **External customer id** (required): a stable ID for this customer, ideally their Stripe ID, `{{trigger.stripe_customer_id}}`. If you map Plandalf’s own customer number by mistake, Plandalf swaps in the Stripe ID for you.
-   **Partner id** (required): `{{trigger.session_properties.tolt_partner_id}}`.
-   **Click id**: `{{trigger.session_properties.tolt_click_id}}`. Optional, but it makes attribution more accurate.
-   **Name**: `{{trigger.customer_name}}`.

If Tolt already has a customer with that email, the step looks them up in your **Program ID** and returns that record. Its `id` output is Tolt’s own customer ID, which the next step needs.

### Create Transactions From Invoice

Records the paid invoice in Tolt, one transaction per line item. It is only available with the **Invoice Paid** trigger.

-   **Invoice id** (required): `{{trigger.invoice_id}}`. Plandalf reads the line items, amounts and products from the invoice.
-   **Tolt customer id**: pick `id` from the Find or Create Customer step in the variable menu. Don’t use the trigger’s `customer_id` or `stripe_customer_id`.
-   **Click id**: optional. If it’s empty, Plandalf uses the click ID saved on the checkout. With no click ID at all, the step is skipped.

Each transaction is labelled with the invoice number, plus the line item for invoices with several products. Tolt ignores a transaction it has already recorded, so re-running the step is safe.

## Example: credit affiliates on every paid invoice

The **Record Tolt referral commission** template builds this for you: open **Automation → Templates**, choose it and pick your checkout. It fills in every field below for you. A sequence added from the template before 14 October 2026 left some of them empty, so check an older one against these steps.

1.  [Set the trigger](#tolt-example-trigger)

    Choose **Plandalf** and **Invoice Paid**. Under **Offer**, pick the checkout affiliates promote. On **3\. Test**, pick a recent paid invoice as the sample record.

2.  [Find or create the Tolt customer](#tolt-example-customer)

    Add **Tolt**, **Find or Create Customer** with your Tolt account. Map **Email**, **External customer id**, **Partner id**, **Click id** and **Name** as listed above. Run its test with an invoice that came through an affiliate link.

3.  [Record the transactions](#tolt-example-transactions)

    Add **Tolt**, **Create Transactions From Invoice**. Set **Invoice id** to `{{trigger.invoice_id}}` and pick `id` from the previous step for **Tolt customer id**.

4.  [Test and turn it on](#tolt-example-on)

    Open a Tolt referral link in a private window, buy through your checkout, and check the sale and partner in Tolt. Then turn the sequence **On**.

Test purchases skip automations by default. To test with a test card, switch on **Run on test purchases** in the sequence’s **Settings**. The Tolt steps still write to the Tolt account on your connection, so use a test partner.

If Tolt also receives payments through its own Stripe connection, choose one of the two routes for these checkouts, or the same sale can be credited twice.

## Common errors

| What you see | What to do |
| --- | --- |
| A Tolt step fails with a 401 or authorization error | The API key is wrong, or it’s the public `pk_…` key. Open the connection in **Automation → My apps**, paste the secret key from **Settings → Integrations** in Tolt, and click **Save Changes**. |
| Find or Create Customer is **skipped** | No partner ID reached the checkout. The buyer didn’t come through an affiliate link, or the configuration above is missing on the page that opened checkout. |
| Create Transactions From Invoice is **skipped** | The checkout has no Tolt click ID. Check the configuration above and that Tolt’s script runs on the page. |
| “has no Stripe `prod_…` on its product” | A product on the invoice isn’t linked to a Stripe product. Link or sync it with Stripe, then re-run the step. |
| Tolt answers “Invalid ID” | **Tolt customer id** isn’t Tolt’s own ID. Pick `id` from the Find or Create Customer step. |
| “lookup failed (program\_id missing or email not in program)” | Add or correct the **Program ID** on the connection. It must match the program on your website. |
| The same sale shows twice in Tolt | Tolt is also reporting it through Stripe. Turn off one of the two routes for these checkouts. |

## Related guides

-   [Automations overview](https://plandalf.com/docs/product-guides/integrations/plandalf)
-   [Tolt with Plandalf checkout](https://plandalf.com/docs/product-guides/platforms/tolt)
-   [Moving an existing Tolt program](https://plandalf.com/docs/product-guides/affiliates/migrate-from-tolt)
-   [Plandalf with Tolt](https://plandalf.com/platforms/tolt)

Source: https://plandalf.com/docs/product-guides/integrations/tolt