# Referrals with Lemon Squeezy

A signing secret Bolt Claw makes for you: orders, renewals and refunds. Lemon Squeezy sends no discount code.

Connect Lemon Squeezy and every order, subscription renewal and refund reaches
the program, credited to the partner whose link brought the customer.

## Add a webhook

1. Open the program, **Setup**, **Billing**, **Lemon Squeezy**. Lemon Squeezy asks
   you to type a signing secret, so Bolt Claw makes one and shows it **once**:
   copy it now, with the endpoint URL.
2. In Lemon Squeezy: **Settings**, **Webhooks**, **Add webhook**. Paste the URL
   and the signing secret, and select `order_created`, `order_refunded`,
   `subscription_payment_success` and `subscription_payment_refunded`.

Lost the secret? **Make new ones** replaces it; paste the new one into Lemon
Squeezy straight away.

## Pass the referral to checkout

Add the code to the checkout URL as custom data:

```js
const url = new URL(checkoutUrl); // your Lemon Squeezy checkout link
url.searchParams.set("checkout[custom][boltclaw_ref]", BoltClawReferral.code() ?? "");
url.searchParams.set("checkout[custom][boltclaw_customer_id]", "acme-user-10442");
```

From the API, the same goes in `checkout_data.custom`. A subscription's first
payment is counted once, as its order; each renewal after it is a renewal.

## Refunds

`order_refunded` and `subscription_payment_refunded` carry the running total
refunded, so a partial refund takes back that share. Lemon Squeezy has no
dispute event.

## Discount codes

Lemon Squeezy sends no discount code at all, so a sale made with a code alone
cannot be credited. Use partner links, or pass the referral at checkout as above.

## Test mode

Lemon Squeezy says whether each event is from test mode; a test order is
recorded as test data.

## 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 in Lemon Squeezy's test mode. 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-lemonsqueezy 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. -->