Connect Lemon Squeezy

You need a Lemon Squeezy store and a website in Revfaro with tracking installed. Open Website settings › Setup, go to Connect payments and choose the Lemon Squeezy tab.

These steps work with the script or npm SDK. With npm, initialize tracking on checkout and return pages, and use your shared tracker.attribution() instead of window.revfaro?.attribution?.() in browser examples. The SDK does not create a window global.

1. Add the webhook in Lemon Squeezy

   In Lemon Squeezy, go to Settings › Webhooks and add a webhook with your website's address from the Lemon Squeezy tab:

   Copy

   https://revfaro.com/api/webhooks/lemonsqueezy/YOUR_SITE_ID

   Select order_created, order_refunded, subscription_payment_success and subscription_payment_refunded. Add it in live mode: test-mode orders are acknowledged but never counted.

2. Use the same signing secret in both places

   Lemon Squeezy asks you to choose the webhook's signing secret, a random string of 6 to 40 characters. Click Generate a secret in the Lemon Squeezy tab to get one, enter the same secret in Lemon Squeezy, then click Save in Revfaro. The tab shows Connected.

3. Pass the visitor to your checkout

   When your server creates a checkout with the Lemon Squeezy API, add the visitor's cookies as custom data:

   checkout.tsCopy

   import { createCheckout } from '@lemonsqueezy/lemonsqueezy.js';
   
   const jar = await cookies(); // next/headers
   
   await createCheckout(STORE_ID, VARIANT_ID, {
     checkoutData: {
       custom: {
         rf_visitor_id: jar.get('rf_vid')?.value ?? '',
         rf_session_id: jar.get('rf_sid')?.value ?? '',
       },
     },
   });

   Calling the REST API directly? The same two keys go into data.attributes.checkout_data.custom.

4. Send buyers back to your site

   In each product's Confirmation modal and Email receipt settings, set the button link to a page on your site with the order number:

   Copy

   https://example.com/thanks?order_identifier=[order_identifier]

   Use the UUID order_identifier; sequential order_id values are not accepted for attribution because they can be guessed. Lemon Squeezy fills in [order_identifier], and Revfaro links the order to whoever lands there, even without custom data. The page must load the script and must not be excluded.

Using checkout links and Lemon.js

Hosted checkout links (https://STORE.lemonsqueezy.com/checkout/buy/…), including Lemon.js overlay buttons, need no code: the script adds checkout[custom][rf_visitor_id] and checkout[custom][rf_session_id] to them, which Lemon Squeezy saves as custom data.

Opening a checkout from your own code, such as LemonSqueezy.Url.Open(url)? Add the same parameters yourself:

const { rf_visitor_id, rf_session_id } = window.revfaro?.attribution?.() ?? {};
const url = new URL('https://STORE.lemonsqueezy.com/checkout/buy/VARIANT');
if (rf_visitor_id) {
  url.searchParams.set('checkout[custom][rf_visitor_id]', rf_visitor_id);
  url.searchParams.set('checkout[custom][rf_session_id]', rf_session_id);
}
LemonSqueezy.Url.Open(url.toString());

What Revfaro records

• Orders: order_created, including the first payment of a subscription.
• Renewals: subscription_payment_success is credited to the visitor who first subscribed.
• Refunds: order_refunded and subscription_payment_refunded are subtracted, partial refunds included.
• Currency: when your website's revenue currency is USD, orders paid in another currency are counted with Lemon Squeezy's USD amount.

Requests are checked against Lemon Squeezy's X-Signature header, so only your store can send payments to your website.