# Referrals with Recurly

An endpoint secret and a read-only API key: every invoice is read from Recurly before it counts.

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:

```js
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](https://boltclaw.ai/docs/referral-setup)
for the whole setup status and what test data never does.

<!-- https://boltclaw.ai/docs/referral-billing-recurly as markdown. Generated from openapi.yaml; API version 1.22.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->