Digital products and SaaS on Lemon Squeezy · ~12 min

Connect Lemon Squeezy to RevFast

API key in RevFast, webhooks for order_created, and checkout custom data — Lemon returns custom fields as meta.custom_data on the webhook.

1. 01

   Step 1 — Install tracking on your live site

   RevFast must see pageviews before checkout. The tracker sets a first-party cookie named ros_uid — that value is how we tie a sale to the last visit. 1. Sign in to RevFast → Settings → Site. 2. Copy the script tag and paste it just before </head> on every public page (homepage, pricing, blog, app shell — not only checkout). 3. Publish or deploy your site. 4. Open the homepage in a normal browser window (not a blocker that strips cookies). 5. In RevFast, wait until tracking shows at least one pageview (usually within a few seconds). If ros_uid never appears, fix tracking before connecting payments. A webhook alone cannot guess which visitor paid.

2. 02

   Step 2 — Connect Lemon Squeezy in RevFast

   1. RevFast → Settings → Payments → Lemon Squeezy. 2. Lemon Squeezy → Settings → API (https://app.lemonsqueezy.com/settings/api) → Create API key. 3. Paste the key in RevFast → Connect. Store ID is optional — we can detect it from the API. RevFast registers webhooks on your public HTTPS app URL (https://revfast.app or NEXT_PUBLIC_APP_URL on self-host). • Click Connect — we call the provider API and register the webhook when the URL is valid https. • If auto-registration fails, copy the Webhook URL from Settings → Payments and add it manually in the provider dashboard. When provisioned, RevFast registers webhooks for order_created, subscription_payment_success, and order_refunded.

3. 03

   Step 3 — Webhook manually (if needed)

   1. Lemon Squeezy → Settings → Webhooks → Add webhook. 2. URL: full RevFast Webhook URL from Settings → Payments (includes ?site= and ?key=). 3. Events: • order_created — new purchases • subscription_payment_success — renewals • order_refunded — refunds 4. Signing secret: set a strong secret in Lemon and paste the same value in RevFast. Lemon signs with the X-Signature header.

4. 04

   Step 4 — Pass ros_visitor_id as custom data

   Lemon Squeezy does not use "metadata". Use custom data on the checkout; it appears on the webhook as meta.custom_data.ros_visitor_id. Overlay / buy link (no backend): Append query params to your checkout URL. API checkout: Send checkout_data.custom in the create-checkout payload.

   // Read the RevFast visitor cookie (set by tracker.js on your marketing site)
   const ros_visitor_id =
     document.cookie.match(/(?:^|; )ros_uid=([^;]*)/)?.[1]?.trim() || "";
   
   const ros_session_id =
     document.cookie.match(/(?:^|; )ros_sid=([^;]*)/)?.[1]?.trim() || "";
   
   // REST API — POST https://api.lemonsqueezy.com/v1/checkouts
   {
     "data": {
       "type": "checkouts",
       "attributes": {
         "checkout_data": {
           "custom": {
             "ros_visitor_id": ros_visitor_id,
             "ros_session_id": ros_session_id
           }
         }
       },
       "relationships": {
         "store": { "data": { "type": "stores", "id": "YOUR_STORE_ID" } },
         "variant": { "data": { "type": "variants", "id": "VARIANT_ID" } }
       }
     }
   }
   
   // Buy link / overlay
   https://YOURSTORE.lemonsqueezy.com/checkout/buy/VARIANT_ID?checkout[custom][ros_visitor_id]=PASTE_ROS_UID

5. 05

   Step 5 — Run a test payment and check Revenue

   1. Use the provider's test mode (Stripe test cards, Polar sandbox, Razorpay test keys, etc.). 2. Complete a real checkout flow on your site — the same path a customer uses. 3. In RevFast, open Revenue (or Customers). Within a minute you should see the order amount next to the pages that visitor viewed. Still empty? • Open Settings → Payments and confirm the integration shows Connected. • In the provider dashboard, open Webhooks → recent deliveries. Look for HTTP 200 from RevFast, not 401/404/500. • Confirm checkout sent metadata.ros_visitor_id (or the provider-specific field in this guide) and that the buyer had ros_uid set before paying. • Ad blockers and cross-domain checkout (pay on another domain without the snippet) break attribution — keep checkout on the same site that runs the tracker, or pass the id explicitly.

6. 06

   Common mistakes

   • Snippet only on the marketing site but checkout on another domain without passing ros_visitor_id. • Using publishable keys (Stripe pk_) instead of secret keys / API tokens. • Fulfilling on the browser "success" page instead of waiting for the webhook (always trust the webhook). • Polar / Lemon webhooks set to Slack or Discord format instead of Raw JSON. • Paytm webhook not on https port 443. • Stripe subscriptions missing subscription_data.metadata (only session metadata was set).

Connect Lemon Squeezy to RevFast.

1. tracker.js → ros_uid on site before checkout.
2. RevFast Settings → Payments → Lemon Squeezy API key → Connect.
3. Webhook URL with site/key params; events order_created, subscription_payment_success, order_refunded; X-Signature secret in RevFast.
4. checkout_data.custom.ros_visitor_id (API) or checkout[custom][ros_visitor_id] on buy URL.

Stuck? Email hello@revfast.app or open onboarding → Need help?