Plandalf
Browse Product guides

Plandalf Affiliates with Plandalf checkout

Use this guide when Plandalf manages both your affiliate program and your checkout, including a checkout embedded on WordPress, Divi, or another website.

Enable your affiliate program, install the SDK on your site, and send visitors through partner links. Plandalf carries the referral through checkout and records eligible commissions after payment. You do not need to configure an automation sequence to record native affiliate commissions.

Note. Early access This guide describes the current affiliate preview. Complete the test below in your environment before accepting live referrals.

How it works

  1. A visitor follows a partner link, such as https://your-site.com/?via=sarah.
  2. The SDK reads the partner code and asks Plandalf to record the click. Plandalf returns an rt_… referral token.
  3. The SDK saves the token in browser storage and the pf_rt cookie, within the program’s attribution window.
  4. Your buy button opens checkout. The SDK includes the referral evidence in the checkout session request.
  5. After a successful payment, Plandalf checks the evidence and program rules, records the sale, and decides the commission.
  6. For subscriptions, the saved customer-to-affiliate relationship lets later paid invoices resolve the affiliate without another browser visit.

The browser remembers the referral before purchase. Plandalf’s server decides who earns commission and remembers the customer relationship afterward. Clearing browser storage or switching devices before that relationship is established can lose attribution; a later identify() call does not reconstruct the missing click.

Open Affiliates, create and enable a program, and choose the commission rate. Add or approve the partner whose link you will use. For a subscription, also choose a recurring commission policy.

Open Affiliates → Setup and copy the tracking script and test link. Use the script generated for your organization; acme.plandalf.dev in these examples is a placeholder. The script, checkout, and affiliate program must belong to the same organization.

Your partner link normally looks like https://your-site.com/?via=PARTNER_CODE. Use the actual link from Plandalf. via identifies the affiliate; pf_ref is a separate buyer/promo identifier.

Embedded checkout or buy button

Install the full SDK on the landing page and any page that opens your checkout:

<script src="https://acme.plandalf.dev/js/plandalf-sdk.js" async></script>

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

Replace the example script URL and offer slug with your own. If you already have the SDK and a Plandalf embed or buy button, keep them; install the SDK only once. On WordPress with Divi, load the script through your site’s script configuration and put the button in a Code module.

When a visitor arrives through a partner link, the SDK records the click. When it opens the checkout with present() or mount(), it automatically includes the referral token in the checkout session request. If you configured referral tracking to require consent, capture starts after consent is granted.

You do not need to add affiliate metadata manually or call the affiliate sales API for that purchase.

Do I need configure(), identify(), or an automation?

  • Organization’s SDK script: loads the affiliate configuration and captures valid partner links.
  • configure(): optional overrides, such as link decoration. No Tolt-style metadata or properties mapping is required for native attribution.
  • identify(): supplies buyer identity. It does not register an affiliate lead or create the customer-to-affiliate relationship by itself. Guest checkout can collect the buyer’s details.
  • present() / mount(): opens checkout and passes the captured referral automatically.
  • Automation sequence: optional for your own follow-up tasks. Native sale attribution and commission recording do not depend on a sequence.

For a logged-in customer, use your existing identification flow before opening checkout. Keep buyer identity separate from the affiliate’s link code and referral token.

Copy the checkout’s actual hosted URL and make it the destination of the partner link. Keep the partner’s configured link parameter, normally via, on that URL. Plandalf reads it when creating the checkout session.

If the buyer first visits your website and then follows a link to a checkout on another domain, install the SDK on the landing page and add the destination hostname to its decoration setting:

<script
  src="https://acme.plandalf.dev/js/plandalf-sdk.js"
  data-config-referral-decorate="checkout.example.com"
  async
></script>

Replace checkout.example.com with the hostname of your real checkout URL. The SDK adds the captured pf_rt referral token when the buyer clicks a matching link. This applies to ordinary links; custom JavaScript redirects must carry the token themselves.

A checkout session created by your own code

Pass referral_token when your code creates the Plandalf checkout session. Read the token from the referral handle as shown in the custom checkout guide. Setting a generic field such as metadata.affiliate_id does not create native affiliate attribution.

3. Complete a test payment

  1. Copy the built-in test partner link from Affiliates → Setup.
  2. Open it in a fresh browser session, then use your normal buy button or hosted checkout link.
  3. Complete a payment using your checkout’s test mode and test payment provider.
  4. Open Affiliates → Sales, select test mode, and open the sale.
  5. Confirm the partner, paid amount, commission, and attribution explanation. A click alone does not prove that a sale was credited.

For an example USD 100 purchase before tax at 20%, expect a USD 20 commission when the program also pays in USD. It normally starts pending until the hold period ends.

What happens after payment?

Plandalf validates referral evidence on the server, records the paid sale, and creates the commission decision. Refunds adjust the commission ledger. Subscription renewal invoices use the saved customer-to-affiliate relationship; the buyer does not need another referral click.

Keep Stripe as an external sales source for checkouts created outside Plandalf. It is not an extra setup requirement for Plandalf-created checkout sales. Do not also report those same purchases through the sales API.

Subscriptions: verify the first payment and a renewal

Use a recurring price in your Plandalf checkout and choose the program’s recurring commission policy. The first attributed sale establishes the customer relationship. Later eligible paid invoices use that relationship; the original cookie does not need to survive for the subscription’s lifetime.

For a USD 100 monthly subscription at 20%, Every payment, ongoing can earn USD 20 on the first invoice and another USD 20 on the next eligible invoice, assuming USD payouts and no tax or other adjustments. First payment only earns on the first eligible paid purchase.

After the first test purchase:

  1. Generate and pay the next invoice using your payment provider’s test tools, without another partner-link visit.
  2. Confirm a second sale for the same partner and the commission expected under your policy.
  3. Replay the same payment event and confirm it does not create another commission.
  4. Refund a test payment and confirm its commission is adjusted.

The payment connection, webhook delivery, and background processing must be working for the renewal to reach Plandalf. A subscription signup or success page alone does not prove that a paid renewal was processed. See the subscription guide for trials, duration limits, and failed payments.

If Tolt is also installed

Tolt’s IDs and Plandalf’s native referral tokens are separate. Installing Tolt does not automatically turn its partners into Plandalf partners. Keep their globals and cookies separate and choose which system owns commissions for each purchase.

If Tolt owns your affiliate program and Plandalf only handles checkout, follow Tolt with Plandalf checkout, including its metadata and automation setup.

Paying partners

Recording a commission does not send money. Review approved balances, pay manually or through your PayPal workflow, and record the payment reference. Stripe affiliate payouts are disabled in this release; Stripe can still process your customers’ subscription payments.

Next steps

Feature detail