Plandalf
Browse Product guides

Affiliate tracking for subscriptions

The first attributed sale connects the customer to the affiliate. Each later paid invoice uses that saved relationship. The buyer does not need to return through the affiliate link every month, and the original browser cookie does not need to last for the whole subscription.

Note. Early access This guide describes the current affiliate preview. Verify both the first payment and a renewal in test mode before launching your program.

1. Choose which payments earn commission

Open Affiliates → Settings → Commission rules → Recurring commissions.

First payment only

The first eligible paid purchase earns commission. Later renewals do not earn. A free trial does not use up the first payment.

Every payment for a set period

Eligible paid renewals and repeat purchases earn within the configured number of months.

Every payment, ongoing

Eligible paid renewals and repeat purchases earn while the referral relationship remains active.

For a fixed period, the clock starts at the first attributed sale. That can be a zero-value trial event if your checkout reports it. A three-month policy means three calendar months, not three invoices.

The relationship is attached to the customer, not just one subscription. Eligible repeat purchases by that customer can also earn under the policy. The saved relationship includes the rate and duration, so changing program settings does not rewrite existing customers’ agreed terms.

For example, a USD 100 monthly subscription at 20% earns USD 20 on each eligible paid invoice, before any adjustments and assuming USD payouts. With First payment only, it earns USD 20 once. With Every payment, ongoing, the second paid invoice earns another USD 20.

2. Set up the first payment

Choose the path that creates your subscription:

Plandalf checkout

Follow Affiliates in Plandalf checkouts. Use a recurring price in your checkout and carry the referral into the first checkout session.

Plandalf links its customer and Stripe subscription records to the referred sale. Subsequent paid Stripe invoices can match that customer without the browser token. You do not need to send a second sale from your own webhook or enable the external Stripe source for this native checkout path.

Follow Affiliates with Stripe. Connect the Stripe account, enable the matching test/live sales source, and carry referral evidence into the first checkout.

When creating a subscription Checkout Session yourself, put the referral in both the Session metadata and subscription_data.metadata. That lets the first paid invoice carry referral evidence even if invoice and checkout webhooks arrive in a different order.

Plandalf records the paid invoice as the subscription sale. The subscription Checkout Session supplies attribution evidence; it is not a second commissionable payment. Renewals match the Stripe customer ID and saved affiliate relationship.

Another billing system or custom checkout

Use the affiliate sales API. Your server must report every paid invoice. Tracking a click or creating a subscription does not tell Plandalf that a renewal was paid.

Send the referral token on the first sale, and send the same stable customer.external_id on every invoice. Use a new external_id for each invoice and keep source and test consistent.

First paid invoice, sent from your server to POST /api/v1/affiliate/sales:

{
  "source": "my-billing",
  "external_id": "invoice_001",
  "currency": "USD",
  "amount_cents": 10000,
  "tax_cents": 0,
  "referral_token": "rt_REPLACE_WITH_CAPTURED_TOKEN",
  "customer": { "external_id": "customer_123", "email": "buyer@example.com" },
  "subscription_id": "subscription_456",
  "billing_reason": "initial",
  "test": true
}

Next paid invoice, with no browser token:

{
  "source": "my-billing",
  "external_id": "invoice_002",
  "currency": "USD",
  "amount_cents": 10000,
  "tax_cents": 0,
  "customer": { "external_id": "customer_123", "email": "buyer@example.com" },
  "subscription_id": "subscription_456",
  "billing_reason": "renewal",
  "test": true
}

Authenticate with your organization’s Plandalf API key on the server. Choose customer IDs unique within your organization’s program, even if you use more than one billing system. A subscription_id on its own is not enough to match a customer. Prefer a stable customer ID over relying on an email address that can change.

Retry an invoice with the same identity and payload. Never use the subscription ID as the sale external_id: all its renewals would then share one sale identity. Use one reporting path per payment; do not send API sales for invoices already imported by the Stripe source.

3. Verify a renewal, not just signup

  1. Use a fresh test customer and the test partner link. Choose a policy that includes renewals.
  2. Complete the first test payment. Check its affiliate and commission under Affiliates → Sales in test mode.
  3. Generate and pay the next test invoice using your billing provider’s test tools, or send the second API example with the same customer ID. This needs a real renewal event in the test environment; revisiting the success page does not simulate it.
  4. Confirm a second sale appears for the same affiliate without another referral click.
  5. Replay the same event. Confirm it does not create another sale or commission.
  6. Refund a test payment. Confirm its commission adjusts rather than leaving the full balance payable.

Also test a free trial converting to its first paid invoice and a fixed-duration customer whose period has ended. Those check different rules from a normal renewal.

Trials, failed payments and cancellation

  • Free trial: a valid attributed zero-value sale can establish the customer relationship, but earns no money. The first later paid invoice can earn.
  • Failed or unpaid invoice: no paid-sale commission should be recorded. Custom integrations must wait for confirmed payment.
  • Cancellation: does not create a refund by itself. Previously earned commissions remain subject to refunds, disputes and your approval rules; there is no renewal commission without another paid invoice.
  • Refund: adjusts the original commission. Your custom billing integration must report it through the refunds API.
  • Expired duration or inactive affiliate: can prevent a renewal earning. Open the sale’s commission decision to see the reason.

Paying the affiliate is a separate step

Subscription tracking works with manual payments and PayPal exports. Review the balance in Payouts, export if needed, pay through your chosen service, then record the payment reference. Stripe affiliate payouts are disabled in this release; Stripe subscription billing and sales tracking remain available.

Feature detail