TL;DR. Recurly doesn’t ship an affiliate feature, so a Recurly affiliate program means adding a tracking layer: a homegrown webhook relay, an agency with spreadsheets, or a platform with a native Recurly integration. The native route is a read-only API key, one XML webhook, and a rekomi_ref custom field on the subscription. From there, paid invoices, renewals, refunds, and voids all settle commissions on their own.
A Recurly affiliate program starts from a fact most guides gloss over: Recurly is subscription billing that runs on top of the payment gateway you already use, and it doesn’t ship affiliate tracking of its own. That combination decides everything about how referral tracking has to work, and once you see the shape of it, the whole setup is honestly pretty tidy. Rekomi, the affiliate software I build, has a native Recurly integration I wrote myself, so I know this plumbing down to the individual notification names.
This guide covers why subscription businesses on Recurly are such strong candidates for an affiliate channel, the three ways to actually run one, what the native setup involves (including the one Recurly plan limitation you should know before you start), and exactly what gets tracked once you’re connected.
Why Recurly businesses add affiliate programs
Because recurring billing turns a single referral into a stream of payments, and that changes the math of the whole channel. When a referred customer on a $79/mo plan sticks around for a year, a 20% recurring commission pays the affiliate $15.80 a month, $189.60 across the year, against $948 you collected. You paid for retention, not just a click, and the affiliate built something closer to MRR than to a one-off bounty. That deal is genuinely good for both sides, which is why SaaS affiliates seek out programs with recurring terms.
Teams pick Recurly for control: it orchestrates plans, trials, dunning, and invoicing while payments keep flowing through your own gateway, whether that’s Stripe, Adyen, Braintree, or GoCardless. The good news for tracking is that Recurly is the source of truth for every one of those invoices. A tracking layer that listens to Recurly sees every payment identically, no matter which gateway processed the card, so your payment routing never changes. If you want the deeper background on how this category of tooling works, my affiliate tracking software guide covers it from first principles.
Three ways to run a Recurly affiliate program
Route 1: build it yourself on Recurly webhooks. Recurly publishes webhook notifications for invoices, payments, refunds, and subscription lifecycle events, so a developer can absolutely wire up a relay that credits referrals. Plan for the real scope, though: you’d parse XML payloads, de-duplicate Recurly’s retry deliveries, carry the referral from the visitor’s browser into the subscription record, handle refunds and voided payments as reversals, and then still build affiliate signup, dashboards, payouts, and tax forms. The first 20% is a fun weekend; the other 80% is a product.
Route 2: an agency or a spreadsheet. Plenty of programs start with a partnerships hire reconciling referrals in a sheet each month, and at 3 partners it works. It stops working the month an affiliate asks why their number doesn’t match yours and you have no event trail to answer with. Manual reconciliation also quietly skips refunds, which means you overpay and never find out.
Route 3: a platform with a native Recurly integration. The list here is shorter than you’d expect. FirstPromoter and impact.com both run credible server-side Recurly integrations, and they’re solid products; Rewardful, the tool most Stripe-first founders know, doesn’t support Recurly today. Rekomi’s integration is in this camp too, and since it’s mine, the rest of this article walks that setup as the concrete example. The parts that matter (the custom field, the webhook, the plan caveat) apply to any server-side route you choose.
What the native setup looks like
Three pieces, all summary level here; the Recurly setup docs have every click and code snippet.
- A read-only API key and your region. Recurly runs a US region (v3.recurly.com) and an EU region (v3.eu.recurly.com), so you pick yours, then create a private API key under Integrations > API Credentials with the read-only box checked. Rekomi validates the key live against your region, and if the key actually belongs to the other region, you get a region suggestion instead of a cryptic error. The key is never used to change anything in your Recurly site.
- One XML webhook with Basic Authentication. In Recurly’s admin UI, under Integrations > Webhooks, you add a single endpoint: the per-workspace URL Rekomi generates, the XML format, and Basic Authentication credentials that Rekomi mints for you. That auth step matters because Recurly signs its JSON webhooks but not its XML ones, and the XML payloads are the ones that carry full invoice data, so every delivery gets authenticated before anything is processed.
- A
rekomi_refcustom field on the subscription. Recurly hosts checkout on its own domain, so the referral has to travel from the visitor’s browser into the subscription record. The Rekomi head script captures the affiliate click on your marketing site, your frontend reads it withwindow.Rekomi.getReferral(), and your backend sets it as arekomi_refcustom field when it creates the subscription. This step is required for new-customer attribution: skip it and paid invoices arrive with no referral attached.
One honest caveat before you start: custom fields are a Recurly Pro and Elite feature (up to 5 and 10 fields respectively), and the Recurly Starter plan doesn’t support them. On Starter there’s no field to stamp, so new-customer attribution isn’t available; renewals of customers who were already attributed still track fine on any plan. If you’re on Starter and serious about an affiliate channel, price the plan upgrade into the decision.
Reliability is better than you’d guess for a webhook-based system, and this is the part I love about Recurly’s design: deliveries that fail get retried automatically, up to 10 times over roughly three days, and every notification keeps a manual Retry button in your Recurly console for 15 days after that. A brief outage on either side heals itself on the next retry, and retried deliveries are de-duplicated so nothing double counts.
What gets tracked once you’re connected
Every movement of money, in both directions. That second direction is my one hard stance on this page: a tracking layer that credits sales but can’t see refunds and voided payments will systematically overpay your affiliates, and on Recurly specifically, voids are a separate notification from refunds, so a relay that only handles successful_refund_notification misses real reversals. Here’s the full picture:
- Paid invoices book conversions. The first paid charge invoice of a subscription records the new-customer conversion and credits the right affiliate from the
rekomi_reffield. - Renewals arrive as more paid invoices and record recurring commissions automatically, matched from your customer history with zero extra API calls. This is where the $15.80/mo from the earlier example keeps accruing without anyone touching anything.
- Refunds claw back commission proportionally, per refund transaction. Refund 40% of that $79 invoice ($31.60 back to the customer) and exactly 40% of the $15.80 commission ($6.32) comes back off the affiliate’s balance. Multiple partial refunds keep clawing back until the original amount is exhausted.
- Voided payments reverse the full transaction amount, distinct from refunds, in the same audit trail.
Both sides of the ledger settle themselves, so the number an affiliate sees in their dashboard is the number you’d get from re-deriving it out of Recurly by hand. That symmetry is what makes payouts safe to automate!
Rekomi itself is affiliate software for Recurly and more than a dozen other billing and creator platforms, with the affiliate-facing half built in: signup pages, dashboards, automated payouts, and tax forms. Plans are $19/mo, $39/mo, or $99/mo plus a 3% take charged only on what affiliates actually earn (2.5% on Enterprise), and that take already covers the payouts and tax handling. Every plan starts with a 14-day free trial, so you can connect a Recurly sandbox and watch a test invoice become a commission before paying anything.
Frequently asked questions
Is there a built-in Recurly affiliate program?
No. Recurly is subscription billing and revenue management; it doesn’t include affiliate or referral tracking. To run an affiliate program on Recurly you add a tracking layer that consumes Recurly’s webhooks, either one you build or a platform with a native integration.
Can I run an affiliate program on the Recurly Starter plan?
Only partially. New-customer attribution rides a custom field on the subscription, and custom fields need Recurly Pro (up to 5) or Elite (up to 10); Starter doesn’t support them, so new referrals can’t be attributed on Starter. Renewals of customers who were already attributed still track on any plan.
Which payment gateways does Recurly affiliate tracking work with?
All of them. Recurly sits on top of your gateway (Stripe, Adyen, Braintree, GoCardless, and the rest), and its webhooks report every payment the same way regardless of which gateway processed the card. The tracking layer listens to Recurly, so nothing about your payment routing changes.
Will affiliates keep earning as subscriptions renew?
Yes, when your campaign terms are recurring. Every renewal arrives as another paid charge invoice and records a recurring commission for as long as your terms say, which is exactly why experienced SaaS affiliates favor Recurly-style subscription programs.
What happens if a webhook delivery fails?
Recurly retries it automatically, up to 10 times over roughly three days, and keeps a manual Retry button on every notification in your console for 15 days. The conversion records on whichever retry succeeds, and deliveries are de-duplicated so retries never double count a sale.
Which affiliate platforms support Recurly?
Fewer than support Stripe. FirstPromoter and impact.com both offer real server-side Recurly integrations, and Rekomi supports Recurly natively; Rewardful doesn’t support Recurly today. If a platform’s Recurly story is “use Zapier,” ask specifically how refunds and voided payments get reversed before you commit.
Start with a 1-minute check
Check which Recurly plan you’re on; it takes 1 minute and it’s the only real gate in this whole setup. If you’re on Pro or Elite (or willing to be), you have everything a serious affiliate program needs: create the rekomi_ref custom field, grab a read-only API key, add the webhook, and your first test invoice will show up as a commission the same day. The Recurly setup docs walk every step with copy-paste snippets, and the 14-day trial means the whole experiment is free.
Run your Recurly affiliate program on Rekomi
Rekomi connects to Recurly with a read-only API key and one webhook, records every renewal as a recurring commission, claws back refunds and voids automatically, and handles affiliate payouts and tax forms for you.
Start a free trial
