Referrals with Recurly

Connect Recurly and every paid invoice, renewal and refund reaches the program, credited to the partner whose link brought the customer.

Recurly's webhooks carry ids only, no amounts, so Recurly is the one system that needs two things: the endpoint's secret, and a read-only API key. Every event is confirmed by reading the invoice from Recurly's own API before it counts.

Add an endpoint

1. Open the program, Setup, Billing, Recurly, and copy the endpoint URL.
2. In Recurly: Integrations, Webhooks, New Endpoint, format JSON, with the URL. Paste the endpoint's secret key on the card.
3. In Recurly: Integrations, API Credentials: add a private API key with read-only access, and paste it on the card. Choose your site's region (US or EU).

Recurly signs each delivery with a timestamp; a delivery older than five minutes is refused, and each delivery's id is claimed so a retry records nothing new.

Pass the referral

Define a subscription custom field named boltclaw_ref (Configuration, Custom Fields), then set it when you create the purchase:

await recurly.createPurchase({
  account: { code: "acme-user-10442" },
  subscriptions: [{ planCode: "pro-monthly", customFields: [{ name: "boltclaw_ref", value: ref }] }],
});

The customer is your own id from a custom field, else the account code.

Refunds

A credit invoice from a refund names the invoice it refunds, and takes back that share of the commission. Disputes are not read from Recurly.

Coupons

Codes are not read from Recurly: use partner links or the custom field.

Test mode

A Recurly sandbox site is its own site. Add a second Recurly integration for it and switch Sandbox on.

Check it works

On the program's Setup tab, the Billing row of the setup status turns Connected with the first verified event, and says when a delivery was refused (nearly always the wrong secret). Then press Send a test sale to see a click, a signup, a sale and a refund go through your rules with test data, or make a real test purchase on your Recurly sandbox site. See Connect your billing system for the whole setup status and what test data never does.