Install on Lemon Squeezy

Lemon Squeezy is a Merchant of Record, and Rekomi supports it natively. You paste one API key; Rekomi validates it, creates the webhook on your store, and confirms it registered. From that point on, one-time orders, initial subscription orders, subscription renewals, and refunds flow into Rekomi with no relay code to write or maintain. Still evaluating? See Why Rekomi for Lemon Squeezy →.

One thing to know up front: Lemon Squeezy API keys expire after one year. Rekomi monitors the connection and emails you to reconnect when the key stops working, so plan on a 30-second re-paste once a year.

Connect your store

Step 1. In Lemon Squeezy, open Settings > API and click the + button to create a new API key. Copy it; Lemon Squeezy shows it only once.

Step 2. In Rekomi, go to /dashboard/setup/lemonsqueezy and paste the key. Rekomi validates the key, detects whether it is a test-mode or live-mode key, and lists the stores on your account.

Step 3. If your account has more than one store, pick the store you want to track. Rekomi generates a signing secret and creates the webhook on that store for you, subscribed to exactly the order, subscription, and refund events it needs. There is nothing to configure in the Lemon Squeezy webhook UI, and disconnecting from Rekomi deletes the webhook again.

Attribution: stamp rekomi_ref on your checkouts (required)

Lemon Squeezy hosts the checkout on its own domain, so the affiliate referral has to travel from the visitor's browser into the order record. This step is required: without it, orders arrive with no referral and no commission is credited.

First, make sure the Rekomi head script is installed on your marketing site so the affiliate cookie is set when a visitor lands on an affiliate link:

<script>
  (function(){
    var s=document.createElement('script');
    s.src='https://js.rekomi.com/v1/rekomi.js';
    s.async=true;
    s.dataset.programId='YOUR_PROGRAM_ID';
    document.head.appendChild(s);
  })();
</script>

The program ID is in Settings > Tracking in the Rekomi dashboard.

Then stamp the referral onto every checkout link (Buy buttons, pricing-page links, and the Lemon.js overlay all use the same URLs) as checkout[custom][rekomi_ref]:

<script>
  document.addEventListener('DOMContentLoaded', function () {
    var ref = window.Rekomi && window.Rekomi.getReferral();
    if (!ref) return;
    document
      .querySelectorAll('a[href*="lemonsqueezy.com/buy/"], a[href*="lemonsqueezy.com/checkout"]')
      .forEach(function (a) {
        var url = new URL(a.href);
        url.searchParams.set('checkout[custom][rekomi_ref]', ref);
        a.href = url.toString();
      });
  });
</script>

window.Rekomi.getReferral() returns the referral from the first-party cookie the head script set. Lemon Squeezy carries checkout[custom][...] values into the order's custom data, which is where Rekomi's webhook handler reads rekomi_ref from.

Server-generated checkouts. If you create checkouts server-side with the Checkouts API, pass the referral in checkout_data.custom instead:

{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "custom": { "rekomi_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
      }
    }
  }
}

Read the referral on your frontend with window.Rekomi.getReferral() and send it to your backend along with the checkout request.

What gets recorded

• One-time orders are recorded as one-time conversions when the order is created.
• Initial subscription orders are recorded once, as the first conversion of the subscription (Rekomi de-duplicates the order event and the first payment event, so nothing is double counted).
• Subscription renewals are recorded as recurring conversions on every successful renewal payment, so recurring revenue-share commissions keep accruing automatically.
• Refunds, full or partial, claw back the commission automatically and proportionally, in the same audit trail as the original conversion.

Fallback: server-to-server relay

If you prefer to own the pipeline yourself (for example, you already run a webhook consumer for Lemon Squeezy events), you can skip the native connection and relay events to Rekomi's HMAC-signed S2S endpoint instead: subscribe to order_created (plus subscription_payment_success for renewals and the refund events), verify Lemon Squeezy's X-Signature, and POST the sale to Rekomi with the affiliate referral from the order's custom data. Amounts in Lemon Squeezy webhook payloads are already in cents, so do not multiply by 100 (converted-currency payloads can contain fractional values; round to integer cents). The full endpoint reference, payload shape, and refund endpoint are in the S2S tracking API docs.

Note that native and S2S are mutually exclusive per workspace: pick one source of truth for Lemon Squeezy sales so conversions are never recorded twice.

Troubleshooting

"Connection needs attention" banner or reconnect email. Lemon Squeezy API keys expire after one year, and deleting the key in Lemon Squeezy has the same effect immediately. Create a fresh key in Settings > API and paste it on /dashboard/setup/lemonsqueezy; your tracking history is preserved and the webhook is recreated automatically.

Webhook missing or edited. If someone deletes or edits the Rekomi webhook inside Lemon Squeezy, events stop arriving (the health check monitors the API key, not the webhook itself). Reconnecting from the setup page recreates the webhook automatically.

Orders arrive but no affiliate is credited. The order reached Rekomi without rekomi_ref in its custom data. Verify the stamping snippet runs on every page that links to checkout, that the head script ran before the buyer clicked through (so window.Rekomi.getReferral() has a value), and that server-generated checkouts pass checkout_data.custom.rekomi_ref.

Test orders do not appear. Test-mode and live-mode are properties of the API key, not separate hosts. If you connected a live key, test-mode orders are not delivered to the webhook Rekomi created. Connect a test-mode key to a sandbox workspace to rehearse end to end.

Related

• S2S tracking API reference
• JavaScript pixel reference
• Refund handling