Lemon Squeezy jako merchant of record

Lemon Squeezy jako merchant of record

Lemon Squeezy sprzedaje Twoje produkty cyfrowe we własnym imieniu i to on, a nie Ty, odpowiada przed urzędami skarbowymi za VAT oraz sales tax. Płacisz za to 5 procent plus 50 centów od transakcji. Na dzień 22 sierpnia 2026 platforma nadal przyjmuje nowych sprzedawców, ale należy do Stripe i równolegle buduje swojego następcę pod inną nazwą.

Co robi merchant of record

Merchant of record to firma, która formalnie jest sprzedawcą wobec Twojego klienta. Na paragonie i na wyciągu z karty widnieje jej nazwa, ona wystawia dokument sprzedaży, ona nalicza podatek według miejsca zamieszkania kupującego, ona składa deklaracje i płaci podatek do właściwego urzędu. Ty sprzedajesz produkt tej firmie, a ona odsprzedaje go dalej. Twoja jedyna transakcja podatkowa jest z nią, a nie z tysiącem klientów w czterdziestu jurysdykcjach.

To rozróżnienie decyduje o tym, czy artykuł o Lemon Squeezy ma w ogóle sens. Prowizja 5 procent brzmi drogo obok 2,9 procent u zwykłego procesora płatności, dopóki nie policzysz, ile kosztuje rejestracja do VAT OSS, obsługa progów rejestracyjnych w poszczególnych stanach USA, comiesięczne deklaracje i biuro rachunkowe, które to ogarnia. Dla jednoosobowej firmy sprzedającej narzędzie za 29 dolarów miesięcznie różnica w procentach jest tańsza niż różnica w godzinach.

Zakres jest ograniczony do produktów cyfrowych: SaaS, pliki do pobrania, subskrypcje, członkostwa, kursy. Fizycznych rzeczy tam nie sprzedasz, a lista produktów zakazanych jest w dokumentacji i obejmuje więcej pozycji, niż się spodziewasz.

Stan platformy po przejęciu przez Stripe

Stripe kupił Lemon Squeezy 26 lipca 2024 roku. To nie jest plotka, tylko wpis na oficjalnym blogu platformy. Od tego czasu status produktu zmieniał się na tyle, że przed podjęciem decyzji trzeba go opisać wprost.

28 stycznia 2026 roku JR Farr, współzałożyciel podpisujący się teraz jako "Co-Founder, Lemon Squeezy (Stripe)", opublikował wpis podsumowujący ten okres. Przyznaje w nim trzy rzeczy. Po pierwsze, zespół pracował głównie nad Stripe Managed Payments, czyli rozwiązaniem merchant of record budowanym wewnątrz Stripe. Po drugie, kosztowało to społeczność Lemon Squeezy wolniejsze odpowiedzi wsparcia i rzadsze aktualizacje produktu. Po trzecie, celem jest "zapewnienie użytkownikom Lemon Squeezy łatwego sposobu migracji do Stripe Managed Payments".

Nigdzie nie pada data wygaszenia. Rejestracja działa, cennik jest opublikowany, dokumentacja jest aktualizowana, a marketingowa strona zachęca do zakładania konta. Jednocześnie Stripe Managed Payments obsługuje według tego wpisu sprzedawców w ponad 35 krajach, a dokumentacja Stripe mówi o zgodności podatkowej w ponad 80 krajach. To dwie różne liczby opisujące dwa różne zakresy i nie należy ich mylić.

Jest jeszcze szczegół, którego nie znajdziesz w komunikacie prasowym. Stopka strony lemonsqueezy.com podaje dziś "Sold through Link, LLC f/k/a Lemon Squeezy LLC", czyli podmiot prawny został przemianowany, a skrót f/k/a oznacza "formerly known as". Stopka dokumentacji technicznej wciąż podaje "Lemon Squeezy, LLC". Jeśli podpisujesz umowę albo wpisujesz kontrahenta do księgowości, sprawdź, która nazwa figuruje w Twoim regulaminie, bo dostawca sam nie jest tu spójny.

Wniosek praktyczny: Lemon Squeezy nadaje się dziś do uruchomienia sprzedaży, ale nie do planowania na pięć lat bez planu wyjścia. Traktuj integrację jako coś, co za jakiś czas przepiszesz na Stripe Managed Payments albo na Paddle. Trzymaj identyfikatory zamówień i subskrypcji we własnej bazie, na przykład w Supabase, zamiast odpytywać o nie API dostawcy przy każdym żądaniu.

Prowizje, opłaty dodatkowe i arytmetyka

Nagłówek cennika to 5 procent plus 50 centów od transakcji, bez opłaty miesięcznej. Dokumentacja opłat dokłada do tego trzy dopłaty, które łatwo przeoczyć, bo nie ma ich na stronie z cennikiem:

• plus 1,5 procent za transakcje międzynarodowe, czyli spoza Stanów Zjednoczonych,
• plus 1,5 procent za płatności przez PayPal,
• plus 0,5 procent za płatności subskrypcyjne.

Prowizja liczona jest od całkowitej wartości zamówienia, a więc razem z podatkiem, który i tak trafia do urzędu. To nie jest oczywiste i podnosi efektywny koszt.

Do tego dochodzą opłaty za wypłatę. Przelew bankowy przez Stripe jest bezpłatny dla kont w USA i kosztuje 1 procent dla kont poza USA. PayPal to 50 centów od wypłaty dla kont amerykańskich i 3 procent z limitem 30 dolarów dla pozostałych. Wypłaty idą dwa razy w miesiącu. Osobno wyceniane są funkcje marketingowe: plus 5 procent od płatności odzyskanych mailami o porzuconym koszyku, plus 3 procent od poleceń partnerskich po stronie sprzedawcy i plus 2 procent od wypłat dla partnerów.

Policzmy to na subskrypcji za 29 dolarów miesięcznie sprzedanej klientowi w Polsce, kartą, z wypłatą na polskie konto bankowe.

Efektywnie oddajesz 3,26 dolara z 29, czyli 11,2 procent, a nie 5 procent z nagłówka. Ten sam rachunek dla jednorazowej sprzedaży za 49 dolarów klientowi w USA, bez podatku stanowego i z wypłatą na konto amerykańskie, daje prowizję 2,95 dolara, czyli 6,0 procent. Rozrzut między 6 a ponad 11 procent zależy od tego, gdzie siedzisz i komu sprzedajesz.

Sama dokumentacja opłat podaje własny przykład i jego arytmetyka się zgadza: produkt za 20 dolarów, francuski VAT 20 procent daje 4 dolary, zamówienie 24 dolary, prowizja 0,50 plus 1,20 plus 0,36 równa się 2,06 dolara, do wypłaty 17,94 dolara. Warto zauważyć, że przy produktach tańszych niż 10 dolarów stała opłata 50 centów zjada tak dużą część ceny, że dostawca sam odsyła takie przypadki do zespołu sprzedaży po indywidualną wycenę.

Dwie liczby u dostawcy się rozjeżdżają i podaję obie. Strona cennika w jednym miejscu mówi o 16 metodach płatności, a w innym o maksymalnie 21. Ta sama strona podaje wsparcie dla 95 walut w tabeli porównawczej i 130 z plusem w sekcji pytań. Nie da się rozstrzygnąć, która wersja jest bieżąca, więc przy planowaniu przyjmij niższą.

Lemon Squeezy, Paddle i Stripe obok siebie

Najważniejsza różnica w tej tabeli nie jest w procentach, tylko w wierszu o odpowiedzialności podatkowej.

Stawki Stripe pochodzą z cennika serwowanego dla Polski, bo ceny Stripe zależą od kraju konta. Kluczowy jest ostatni wiersz kolumny środkowej razem z wierszem o deklaracjach: u Stripe płacisz mniej procentowo, ale rejestracja do VAT w Unii, progi nexus w USA i comiesięczne deklaracje zostają Twoim problemem. Stripe Tax policzy podatek, natomiast go za Ciebie nie zapłaci ani nie złoży deklaracji. Jeśli sprzedajesz kilkanaście licencji miesięcznie, ta różnica jest ważniejsza niż każdy procent w tabeli.

W tabeli brakuje jednego gracza, który przy tej samej stawce wejściowej daje coś, czego Lemon Squeezy nie ma. Polar też jest sprzedawcą formalnym i też startuje od 5 procent plus 50 centów, ale oferuje płatne plany obniżające prowizję do 3,4 procent przy stałym abonamencie, więc powyżej pewnego obrotu wychodzi wyraźnie taniej. Nie nalicza też osobnej dopłaty za subskrypcje. Wady dwie i trzeba je zważyć: to znacznie młodsza i mniejsza firma bez zaplecza Stripe, a jej pakiet dla JavaScriptu ma wciąż numer poniżej 1.0, co oznacza, że interfejs może się jeszcze zmienić.

Checkout hostowany i overlay

Masz trzy sposoby doprowadzenia klienta do zapłaty. Najprostszy to link do checkoutu hostowanego, wygenerowany w panelu i wklejony gdziekolwiek. Drugi to overlay, czyli ten sam checkout otwierany w modalu nad Twoją stroną, bez wychodzenia z aplikacji. Trzeci to checkout tworzony przez API, gdy chcesz nadpisać cenę, wstępnie wypełnić dane albo przekazać własne metadane.

Własnego formularza płatności nie zbudujesz. Numer karty zawsze zbiera Lemon Squeezy, bo to on jest sprzedawcą i to on odpowiada za zgodność z PCI. Kolorystykę i teksty dostosujesz, układ nie.

import {
  lemonSqueezySetup,
  createCheckout,
} from '@lemonsqueezy/lemonsqueezy.js'

lemonSqueezySetup({
  apiKey: process.env.LEMONSQUEEZY_API_KEY,
  onError: (error) => console.error(error.message),
})

const { data, error } = await createCheckout(
  process.env.LEMONSQUEEZY_STORE_ID!,
  process.env.LEMONSQUEEZY_VARIANT_ID!,
  {
    checkoutData: {
      email: user.email,
      name: user.name,
      custom: { user_id: user.id },
    },
    productOptions: {
      redirectUrl: 'https://example.com/dashboard',
      receiptThankYouNote: 'Klucz licencyjny jest w tej wiadomosci.',
      enabledVariants: [Number(process.env.LEMONSQUEEZY_VARIANT_ID)],
    },
    checkoutOptions: {
      embed: true,
      media: false,
      subscriptionPreview: true,
      buttonColor: '#111827',
    },
    testMode: process.env.NODE_ENV !== 'production',
    expiresAt: null,
  },
)

if (error) throw new Error(error.message)
const url = data?.data.attributes.url

Pole checkoutData.custom jest tym, o co najczęściej się potykasz. Trafia ono do payloadu webhooka jako meta.custom_data i to jedyny pewny sposób powiązania zamówienia z użytkownikiem w Twojej bazie. Adresu e-mail nie używaj do tego celu, bo klient może zapłacić z innego niż ten, którym się zarejestrował.

Overlay wymaga skryptu Lemon.js i globalnego obiektu LemonSqueezy. Metody są cztery plus dwie partnerskie: Setup, Refresh, Url.Open, Url.Close, Affiliate.GetID oraz Affiliate.Build.

LemonSqueezy.Setup({
  eventHandler: (event) => {
    if (event.event === 'Checkout.Success') {
      // event.data to obiekt zamowienia, ale zaufaj dopiero webhookowi
      window.location.href = '/dashboard?pending=1'
    }
  },
})

LemonSqueezy.Url.Open(checkoutUrl)

Dostępne zdarzenia to Checkout.Success, PaymentMethodUpdate.Mounted, PaymentMethodUpdate.Closed i PaymentMethodUpdate.Updated. W aplikacji jednostronicowej pamiętaj o LemonSqueezy.Refresh() po zmianie widoku, bo nasłuchiwacze przycisków są podpinane raz przy załadowaniu.

Webhooki i weryfikacja podpisu

Nadanie uprawnień w aplikacji musi opierać się na webhooku, nie na przekierowaniu po płatności. Przekierowanie da się sfałszować, wywołując po prostu ten adres URL.

Lemon Squeezy podpisuje żądanie sekretem, który sam ustawiasz przy tworzeniu webhooka, długości od 6 do 40 znaków. Podpis trafia do nagłówka X-Signature jako szesnastkowy HMAC SHA-256 z surowego ciała żądania.

import crypto from 'node:crypto'

export async function POST(request: Request) {
  const raw = await request.text()
  const secret = process.env.LEMONSQUEEZY_WEBHOOK_SECRET!

  const digest = Buffer.from(
    crypto.createHmac('sha256', secret).update(raw).digest('hex'),
    'utf8',
  )
  const signature = Buffer.from(
    request.headers.get('X-Signature') ?? '',
    'utf8',
  )

  if (
    digest.length !== signature.length ||
    !crypto.timingSafeEqual(digest, signature)
  ) {
    return new Response('Invalid signature', { status: 401 })
  }

  const payload = JSON.parse(raw)
  const eventName = payload.meta.event_name
  const userId = payload.meta.custom_data?.user_id

  if (eventName === 'subscription_created') {
    // nadaj dostep uzytkownikowi userId
  }

  return new Response('ok', { status: 200 })
}

Trzy rzeczy psują tę weryfikację najczęściej. Pierwsza to sparsowane ciało żądania: framework, który sam wywoła JSON.parse, zmieni kolejność albo formatowanie i podpis przestanie pasować, więc potrzebujesz surowego tekstu. Druga to timingSafeEqual, które rzuca wyjątkiem przy różnej długości buforów, dlatego długość sprawdzamy wcześniej. Trzecia to funkcje brzegowe: w Next.js trasa obsługująca webhook powinna działać w środowisku Node, bo korzysta z modułu node:crypto, a na Vercel domyślne ustawienie potrafi być inne, niż zakładasz.

Zdarzeń jest siedemnaście: od order_created i order_refunded, przez pełny cykl subskrypcji od subscription_created do subscription_expired, po license_key_created, customer_updated i affiliate_activated. Minimalny sensowny zestaw dla subskrypcji to subscription_created, subscription_updated, subscription_payment_success i subscription_expired. Zdarzenie subscription_updated jest workiem zbiorczym i zawsze niesie aktualny stan, więc jeśli obsłużysz tylko jedno, obsłuż to.

Maile transakcyjne po nadaniu dostępu wysyłaj własnym kanałem, na przykład przez Resend, bo wbudowany moduł mailowy Lemon Squeezy jest wyceniany osobno według liczby subskrybentów i celuje raczej w newslettery niż w powiadomienia systemowe.

Klucze licencyjne i tryb testowy

Klucze licencyjne to funkcja, dla której część zespołów wybiera Lemon Squeezy zamiast czystego procesora płatności. Po zakupie generowany jest klucz, a aplikacja desktopowa aktywuje go pod nazwą instancji, dzięki czemu można ograniczyć liczbę stanowisk.

License API jest osobne od głównego API, ma własny limit 60 żądań na minutę zamiast 300 i nie wymaga klucza API, co pozwala wołać je bezpośrednio z aplikacji klienckiej.

# aktywacja klucza na konkretnym urzadzeniu
curl -X POST https://api.lemonsqueezy.com/v1/licenses/activate \
  -H "Accept: application/json" \
  -d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
  -d "instance_name=MacBook Pro Anny"

# walidacja przy starcie aplikacji
curl -X POST https://api.lemonsqueezy.com/v1/licenses/validate \
  -H "Accept: application/json" \
  -d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
  -d "instance_id=47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"

Odpowiedź zawiera pola activated, error, license_key, instance oraz meta. W obiekcie license_key znajdziesz status, activation_limit, activation_usage i expires_at. Status przyjmuje cztery wartości: inactive przy kluczu bez żadnej aktywacji, active przy co najmniej jednej, expired po upływie terminu lub wygaśnięciu subskrypcji oraz disabled po ręcznym wyłączeniu w panelu.

Tryb testowy jest domyślny na nowym koncie i obejmuje cały przepływ: checkout, subskrypcje, klucze licencyjne i webhooki. Klucze API są związane z trybem, więc klucz testowy nigdy nie dotknie danych produkcyjnych. Karty testowe to między innymi 4242 4242 4242 4242 dla Visy, 4000 0000 0000 9995 dla braku środków i 4000 0027 6000 3184 dla 3D Secure. Dwie pułapki: pobieranie plików jest w trybie testowym wyłączone, więc dostarczania plików tam nie przetestujesz, a produkty utworzone w trybie testowym nie przenoszą się same na produkcję i trzeba użyć opcji "Copy to Live Mode".

SDK, licencja i to, czego brakuje

Tu zaczyna się część, którą trzeba powiedzieć wprost. Oficjalny pakiet @lemonsqueezy/lemonsqueezy.js ma wersję 4.0.0 opublikowaną 5 listopada 2024 roku. Od tamtej pory nie ukazało się żadne wydanie, czyli ponad 21 miesięcy ciszy. Sprawdziłem też gałąź główną repozytorium lmsqueezy/lemonsqueezy.js: plik package.json na main również podaje 4.0.0, więc nie ma nawet niewydanych zmian czekających w kolejce.

# stan na 22 sierpnia 2026
npm view @lemonsqueezy/lemonsqueezy.js version   # 4.0.0
npm view @lemonsqueezy/lemonsqueezy.js time.4.0.0 # 2024-11-05
npm install @lemonsqueezy/lemonsqueezy.js

Skutki są mierzalne, nie teoretyczne. Typ Events w SDK wymienia piętnaście zdarzeń webhooka, a dokumentacja API wymienia siedemnaście. Brakujące to customer_updated i affiliate_activated. Jeśli tworzysz webhook przez createWebhook i chcesz nasłuchiwać któregoś z nich, TypeScript odrzuci poprawną wartość. Obejście jest banalne, bo wystarczy rzutowanie, ale to sygnał, w jakim stanie jest ta biblioteka.

Poza tym pakiet jest przyzwoity: 59 funkcji, pełne typy TSDoc, brak zależności produkcyjnych, engines.node ustawione na wersję 20 lub nowszą, budowany w wariancie ESM i CommonJS. Funkcje nazywają się przewidywalnie, od listSubscriptions i updateSubscription po createUsageRecord i issueOrderRefund.

Licencja jest jednym z nielicznych miejsc, gdzie wszystko się zgadza, i wypada to odnotować, bo bywa inaczej. Sprawdziłem trzy źródła. Plik LICENSE w gałęzi głównej repozytorium zawiera tekst MIT z notą "Copyright (c) 2024 Lemon Squeezy, LLC". Pole license w rejestrze npm ma wartość MIT. Opublikowana paczka po rozpakowaniu waży 340 kB, zawiera plik package/LICENSE z tą samą treścią oraz realny kod w dist/index.js i dist/index.cjs, a nie atrapę. Trzy źródła, jeden wynik, bez niespodzianek.

Uwaga na zakres: MIT dotyczy klienta HTTP, a nie platformy. Sama usługa jest zamknięta i działa na warunkach regulaminu, który dostawca może zmienić. Otwarta licencja SDK nie daje Ci żadnej możliwości uruchomienia Lemon Squeezy u siebie.

Ekosystem poza pakietem JavaScript to oficjalny pakiet dla Laravela oraz nieoficjalne biblioteki społeczności dla Go, Ruby, Rusta, Swifta, Pythona, PHP, Elixira i Javy. Wszystkie te ostatnie są utrzymywane przez pojedyncze osoby, więc przy wyborze sprawdź datę ostatniego wydania zanim wpiszesz je do go.mod albo Gemfile.

Typowe błędy

Nadawanie dostępu na podstawie przekierowania po płatności. Adres redirectUrl może otworzyć każdy, kto go zgadnie. Uprawnienia nadawaj wyłącznie po zweryfikowanym webhooku, a przekierowanie traktuj jako ekran "trwa przetwarzanie".

Wiązanie konta po adresie e-mail. Klient zapłaci z adresu firmowego, a zarejestrował się prywatnym, i konto zostanie bez subskrypcji. Przekazuj identyfikator użytkownika przez checkoutData.custom i czytaj go z meta.custom_data.

Liczenie przychodu z nagłówka cennika. Przy sprzedaży z Europy do Europy realny koszt to około 11 procent, bo dochodzą dopłaty za transakcję międzynarodową, za subskrypcję i za wypłatę. Do prognozy przyjmij liczbę policzoną dla swojego przypadku, nie 5 procent.

Parsowanie ciała żądania przed sprawdzeniem podpisu. Middleware, które automatycznie zamienia JSON na obiekt, unieważnia HMAC. Potrzebujesz surowego tekstu, zanim cokolwiek go dotknie.

Brak obsługi ponownych doręczeń. Ten sam webhook potrafi przyjść dwa razy. Zapisuj identyfikator zdarzenia i traktuj obsługę jako idempotentną, inaczej przy jednej płatności naliczysz dwa okresy rozliczeniowe.

Traktowanie modułu mailowego jako systemu autoryzacji. Lemon Squeezy zna zamówienia, ale nie zna sesji w Twojej aplikacji. Logowanie i uprawnienia zostają po Twojej stronie, w Better Auth albo w Clerk, a płatność jest tylko flagą przypiętą do konta.

Odkładanie planu wyjścia. Skoro dostawca sam mówi o migracji do Stripe Managed Payments, warstwę płatności trzymaj za własnym interfejsem z dwiema, trzema metodami. Wymiana implementacji zajmie wtedy dzień, a nie kwartał.

FAQ

Czy Lemon Squeezy nadal przyjmuje nowych klientów?

Tak. Na 22 sierpnia 2026 rejestracja działa, cennik jest opublikowany, a dokumentacja aktualizowana. Nie ma ogłoszonej daty wygaszenia. Jest natomiast oficjalny wpis z 28 stycznia 2026 mówiący o budowie Stripe Managed Payments i o zamiarze zapewnienia użytkownikom łatwej migracji, więc planuj z założeniem, że kiedyś będziesz się przenosić.

Ile realnie zostaje mi ze sprzedaży?

Z subskrypcji za 29 dolarów sprzedanej klientowi w Polsce, przy VAT 23 procent i wypłacie na konto poza USA, na koncie ląduje 25,74 dolara, czyli koszt wynosi 11,2 procent ceny netto. Przy jednorazowej sprzedaży za 49 dolarów klientowi w USA z wypłatą na konto amerykańskie koszt spada do 6,0 procent.

Czym różni się Lemon Squeezy od Stripe?

Lemon Squeezy jest merchant of record i bierze na siebie naliczanie, składanie deklaracji oraz zapłatę VAT i sales tax. Stripe w układzie standardowym jest procesorem płatności, więc obowiązki podatkowe zostają po Twojej stronie, a Stripe Tax jedynie policzy podatek za dodatkowe 0,5 procent od transakcji. Różnica w procentach jest wtórna wobec różnicy w odpowiedzialności.

Czy mogę zbudować własny formularz płatności?

Nie. Dane karty zawsze zbiera Lemon Squeezy, bo to on jest sprzedawcą formalnym. Masz do wyboru checkout hostowany, overlay przez Lemon.js oraz sesję tworzoną przez API z nadpisaną ceną i danymi. Dostosowujesz kolory, teksty i widoczność elementów, nie układ.

Czy SDK bez wydania od 2024 roku wyklucza użycie platformy?

Nie wyklucza, ale trzeba to wliczyć w koszt. API jest wersjonowane prefiksem /v1 i deklaruje wsteczną zgodność, więc istniejące wywołania działają. Braki widać w typach, na przykład dwóch zdarzeń webhooka nie ma w typie Events. Jeśli nie chcesz tego obchodzić, wołaj API bezpośrednio przez fetch.

Czy klucze licencyjne wystarczą do ochrony aplikacji desktopowej?

Wystarczą do rozliczania stanowisk i odbierania dostępu, bo activation_limit razem z activation_usage ograniczają liczbę instancji, a klucz można wyłączyć w panelu. Nie są zabezpieczeniem przed złamaniem aplikacji, ponieważ walidacja odbywa się po stronie klienta i limit 60 żądań na minutę wymusza buforowanie wyniku lokalnie.