Billing

Lemon Squeezy

Connect Lemon Squeezy: what to pass at checkout, which webhook events, and where the signing secret is.

1. Pass the referral at checkout

const ref = window.referralmeter?.ref() ?? null;

// Checkout API (POST /v1/checkouts), in attributes:
checkout_data: { custom: { referralmeter_ref: ref ?? "" } },

// Or on a hosted checkout URL:
// https://<store>.lemonsqueezy.com/buy/<variant>?checkout[custom][referralmeter_ref]=<ref>

Referralmeter reads referralmeter_ref from that field on the payment Lemon Squeezy sends back. To mark a purchase as credits or a top-up (so your credits rule applies), also set kind: "credits" in the same metadata.

2. Connect the webhook

Lemon Squeezy → Settings → Webhooks → +. URL: the Lemon Squeezy webhook URL from Billing connections. Choose a signing secret and paste the same value into Billing connections.

Lemon Squeezy lets you choose the signing secret (6–40 characters). Use a random one and paste the same value into Billing connections.

Events Referralmeter uses:

order_created
subscription_payment_success
order_refunded
subscription_payment_refunded
subscription_expired

Test mode

Lemon Squeezy flags test-mode orders. They are recorded and never paid out.

Good to know

A new subscription sends both order_created and subscription_payment_success for the same money; Referralmeter counts it once.