Tolt with Plandalf checkout

Keep your affiliate program in Tolt while using Plandalf to take payments. Tolt tracks the referral; Plandalf carries its IDs through checkout and reports the paid invoice through an automation.

There are two setup steps: add the browser handoff once, then configure the paid-invoice sequence. Connecting a Tolt account alone does not install its website script or capture its referral fields.

Warning. Current scope This guide covers the existing Tolt paid-sale automation. The current transaction action labels every transaction one_time, requires click evidence from the checkout or action input, and has no registered refund action. Do not treat this as a complete subscription or refund integration. See the checks below before enabling it for customers.

How the information gets through

A visitor follows a Tolt affiliate link to your website. Tolt’s script supplies the click and partner IDs.
When Plandalf opens checkout, the configuration below reads those IDs and saves them as checkout properties.
After payment, the Invoice Paid trigger exposes the saved properties to the sequence.
Tolt → Find or Create Customer associates the buyer with the Tolt partner.
Tolt → Create Transactions From Invoice reports the invoice line items. Tolt applies its commission rules.

The browser carries attribution evidence. The automation gets the amount, customer, and products from the server’s invoice.

1. Add the website handoff

Install your own Tolt tracking script and your organization’s Plandalf SDK. Use the script URL supplied by Plandalf; acme.plandalf.dev below is a placeholder. Install each script only once.

This example configures the handoff after the Plandalf script loads. If your site already loads the SDK asynchronously, place the configuration in its existing ready callback.

<script async src="https://files.tlt-cdn.com/tlt.js" data-tolt="YOUR_TOLT_PUBLIC_ID"></script>
<script src="https://acme.plandalf.dev/js/plandalf-sdk.js"></script>
<script>
  plandalf("configure", {
    metadata: {
      tolt_referral: () => window.tolt_referral || null
    },
    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>

<button data-plandalf-present="YOUR_PUBLISHED_OFFER_SLUG">Buy now</button>

Use your actual Tolt public ID and published checkout slug. Tolt’s secret API key belongs in the server-side connection, never in this snippet.

The () => functions read the current values when present() or mount() creates a checkout session. They can pick up a tracker that loaded after the configuration ran. They do not wait for a blocked or still-loading Tolt script: test a fast click and verify the saved fields.

Configure this on every page that opens checkout. Tolt’s script must also run on referral landing pages. For WordPress with Divi, load the scripts once through your site’s script configuration and place the buy button in a Code module. Verify the published page with your caching and optimization plugins enabled.

What is stored

The saved checkout properties are flat fields:

tolt_click_id: Tolt’s referral click ID.
tolt_partner_id: the affiliate’s ID in Tolt.
tolt_program_id: the Tolt program associated with that browser referral.

The automation reads them under trigger.session_properties. Do not send a nested properties.tolt_data object using an older example.

identify() supplies the buyer’s identity when you have a signed customer token. It does not register a Tolt lead. Guest checkout can collect the buyer’s details during payment.

Why the snippet includes metadata and properties

These fields have different destinations:

metadata.tolt_referral → Stripe customer metadata: Plandalf adds it when preparing payment, making the referral available to a Tolt integration connected to Stripe.
properties.tolt_* → Plandalf checkout session: exposed as trigger.session_properties, these fields supply the partner and click IDs to the Plandalf automation below.

Capturing both does not itself create a duplicate commission. The reporting configuration determines whether a payment is sent to Tolt through Stripe, through Plandalf’s automation, or through both.

Keep the metadata mapping if your existing Tolt setup uses Stripe customer metadata. The properties mapping does not replace it. Likewise, metadata alone does not supply the fields required by this automation.

Before enabling the sequence, check how your Tolt account receives transactions:

Tolt reports payments through its Stripe connection: verify that it picks up the customer metadata and the resulting purchase. Do not also enable this transaction sequence for the same payments unless you have verified how duplicates are handled.
Plandalf reports payments through the Tolt actions: follow the sequence below. The actions use checkout properties; the metadata mapping is optional for this route.

Saving a referral on a Stripe customer does not by itself prove that Tolt registered the customer, credited a sale, or tracked a renewal. Verify those results in Tolt.

2. Connect your Tolt account

In Automations, add a Tolt action and create or select its connection. Supply:

API Key: the Tolt secret API key.
Program ID: the program you are reporting to. It must match your website’s Tolt program; the browser’s tolt_program_id does not select a server connection automatically.
Own partner id: optional, if you use a Tolt partner ID for your own marketing. This affects Plandalf’s traffic-source labels; it does not replace your commission rules or automatically prevent the reporting action from sending a transaction.

A saved connection alone does not prove the API key works. Confirm the action results with a controlled purchase.

3. Configure the paid-invoice sequence

Choose Plandalf → Invoice Paid (invoice.paid) as the trigger and scope it to the checkout you want to report. Use the sequence editor’s field picker to insert the values below.

First action: Find or Create Customer

Select Tolt → Find or Create Customer and map:

Email: {{trigger.customer_email}}
External customer id: {{trigger.stripe_customer_id}}
Partner id: {{trigger.session_properties.tolt_partner_id}}
Click id: {{trigger.session_properties.tolt_click_id}}
Name: {{trigger.customer_name}} (optional)

Use a stable external customer ID. For this Stripe-backed recipe, confirm stripe_customer_id is populated. The partner and click IDs must belong to the Tolt program in the selected connection.

Second action: Create Transactions From Invoice

Add Tolt → Create Transactions From Invoice after the customer action:

Invoice id: {{trigger.invoice_id}}
Tolt customer id: select the previous customer’s id output in the field picker. This is Tolt’s internal record ID. Do not choose the trigger’s customer_id, stripe_customer_id, or the previous action’s external customer_id.
Click id: {{trigger.session_properties.tolt_click_id}}

The previous step’s reference depends on the ID the editor gives that step. Select its output instead of copying a made-up step name. Older action help mentions tolt_id; the current customer action returns id.

The transaction action reads line items from the invoice and posts one transaction per item. Each product must have a linked Stripe product ID (prod_…). Check that mapping if an action reports a missing product ID.

If there is no partner ID, the customer action skips. If there is no click ID, the transaction action skips. A skipped run does not prove a referred purchase was credited.

If Tolt and Plandalf are both installed

Tolt plus Plandalf checkout is the normal setup for this guide. Plandalf carries the Tolt fields; Tolt owns the affiliate program. You do not need to enable native Plandalf Affiliates for that setup.

If you also enable native Plandalf Affiliates, the two referral systems have separate identities:

Tolt keeps its own tolt_referral / tolt_data values and Tolt IDs.
Native Plandalf uses its rt_… token, pf_rt cookie, and its own partner records.
The same checkout can carry Tolt properties and native Plandalf referral evidence. One ID does not translate into the other, and partners are not automatically imported.

Keep these names separate. Do not configure Plandalf’s compatibility global, cookie, or metadata key to use Tolt’s names while the real Tolt tracker is still running. That can replace a Tolt ID with a Plandalf token.

Use distinct referral parameters for separate programs, for example your existing Tolt parameter and a configured pf_aff parameter for native Plandalf links. Verify the actual generated links and partner mapping. Using via in both systems does not make their affiliate codes interchangeable.

Choose which system owns commissions for each purchase. If both record commissions, both may show a payable balance. There is no automatic comparison mode or protection against paying the same reward in both platforms.

Can Plandalf pick this up automatically?

With the snippet installed, the handoff happens on each checkout automatically. You do not repeat the properties on every present() call. Today, installing both scripts without that configuration is not enough.

A simpler future setup would let the merchant enable “Capture Tolt referrals” once, publish that setting to the SDK, capture the supported Tolt fields when present, and prefill the sequence mappings. It should preserve Tolt’s consent behavior and keep the two sets of IDs separate. That automatic detection and setup is not available yet.

Verify before enabling the sequence

Start with a test checkout and a Tolt program/account you control for verification. A Plandalf test payment does not establish that the outbound Tolt API call is sandboxed; it uses the credentials in the selected connection.

Open a valid Tolt referral link in a fresh browser session.
Open Plandalf checkout and confirm the session contains the three flat Tolt properties.
Complete a controlled payment. Inspect the Invoice Paid trigger’s session_properties and customer fields.
Run the customer action and confirm its id identifies the expected customer in Tolt.
Run the transaction action and confirm the purchase, products, amount, and affiliate in Tolt itself.
Test a direct visitor: the Tolt actions should skip when referral fields are absent.
Retry the same invoice and verify Tolt does not create another commission. Check a multi-item purchase separately.

Subscriptions and refunds need additional work

Do not assume the first sale proves renewals. The current action sends billing_type: "one_time" and requires a click ID from the input or the invoice’s checkout session. A later invoice without those properties can be skipped. It does not use native Plandalf’s saved customer-to-affiliate relationship to resolve a Tolt customer.

The registered Tolt actions currently include customer creation and transaction creation, with no refund action. Automatic renewal attribution, subscription transaction classification, and refund reversal must be implemented and verified before relying on this sequence for those events.

For commissions managed inside Plandalf, use the native subscription guide. That is a separate reporting path with its own customer relationships.