Connect Lemon Squeezy

Lemon Squeezy sends orders and subscription payments to a webhook signed with a secret MetricRaven generates. Checkout custom data links each order to the visit that started it.

Set up the webhook

1. Open Settings → Integrations → Lemon Squeezy

   Choose Set up Lemon Squeezy. Copy the webhook URL and the signing secret; the secret is shown once.

2. Add a webhook in Lemon Squeezy

   In Lemon Squeezy, open Settings → Webhooks and choose +. Paste the URL as the callback URL and the secret as the signing secret.

3. Select the payment events

   Select order_created, order_refunded, subscription_payment_success and subscription_payment_refunded. For subscription goals (trial started, cancelled, ended), also select subscription_created, subscription_updated, subscription_cancelled, subscription_resumed, subscription_expired, subscription_paused and subscription_unpaused. Then save.

Pass the visitor ID at checkout

Lemon Squeezy returns checkout custom data in each webhook's meta.custom_data. Use these keys:

1. Read the visitor ID in the browser

   The MetricRaven script exposes window.analytics.getVisitorId(). Read it when checkout starts and send it to your checkout code:

   script.js

   Copy

   1

   2

   3

   4

   // Read this in the visitor's browser when they start checkout.
   const visitorId = window.analytics?.getVisitorId() ?? null;
   // Send visitorId to your own checkout endpoint alongside its usual request data.
   // Use the authenticated user ID from your backend; do not trust a browser-supplied user ID.

2. Add it to the checkout

   For a checkout link or Lemon.js overlay, add a query parameter:

   Checkout link

   Copy

   1

   2

   3

   4

   5

   // Browser: add the visitor ID to a Lemon Squeezy checkout link.
   const url = new URL("https://YOUR_STORE.lemonsqueezy.com/buy/YOUR_VARIANT_ID");
   const visitorId = window.analytics?.getVisitorId();
   if (visitorId) url.searchParams.set("checkout[custom][metricraven_visitor_id]", visitorId);
   window.location.href = url.toString();

   When you create checkouts on your server, put it in checkout_data.custom:

   Checkouts API

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15

   16

   17

   18

   19

   20

   21

   22

   23

   24

   25

   26

   // Server: create a checkout with the Lemon Squeezy API.
   // visitorId came from your browser; user is your authenticated user (or null for guests).
   const custom = {
     ...(visitorId ? { metricraven_visitor_id: visitorId } : {}),
     ...(user ? { metricraven_user_id: user.id } : {}),
   };
   const response = await fetch("https://api.lemonsqueezy.com/v1/checkouts", {
     method: "POST",
     headers: {
       Accept: "application/vnd.api+json",
       "Content-Type": "application/vnd.api+json",
       Authorization: `Bearer ${process.env.LEMONSQUEEZY_API_KEY}`,
     },
     body: JSON.stringify({
       data: {
         type: "checkouts",
         attributes: { checkout_data: { email: user?.email, custom } },
         relationships: {
           store: { data: { type: "stores", id: "YOUR_STORE_ID" } },
           variant: { data: { type: "variants", id: "YOUR_VARIANT_ID" } },
         },
       },
     }),
   });
   const { data } = await response.json();
   // Redirect the visitor to data.attributes.url

MetricRaven links each payment to a visit using the first of these that is available:

1. The metricraven_visitor_id passed through checkout.
2. The metricraven_user_id (or the provider's customer external ID), matched to a visitor you linked with the Identify API.
3. An earlier payment from the same provider customer, so renewals keep the original attribution.
4. The checkout email, matched to an email you sent to the Identify API.
5. The checkout email, matched to a browser that called payment({ email }) within an hour of the payment.

Can't set custom data on your checkout? See Other Lemon Squeezy methods to match by the buyer's email.