| name | sales-lemonsqueezy |
| description | Lemon Squeezy platform help — payments, subscriptions, tax compliance, digital product delivery, license keys, and checkout as a merchant of record. Use when setting up a Lemon Squeezy store, configuring subscriptions or usage-based billing, generating or validating license keys, webhooks aren't firing or Cloudflare is blocking them, payouts are delayed or frozen, or choosing between Lemon Squeezy vs Gumroad vs Paddle. Do NOT use for general email marketing strategy (use /sales-email-marketing) or checkout optimization strategy (use /sales-checkout). |
| argument-hint | [describe what you need help with in Lemon Squeezy] |
| license | MIT |
| version | 1.0.0 |
| tags | ["sales","payments","subscriptions","digital-products","platform"] |
| github | https://github.com/lmsqueezy |
Lemon Squeezy Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Ask the user:
-
What do you need help with?
- A) Store setup and product configuration
- B) Subscriptions and recurring billing
- C) License key generation or validation
- D) Checkout setup (hosted, overlay, or embedded)
- E) Webhooks or API integration
- F) Payouts, tax, or compliance questions
- G) Email marketing within Lemon Squeezy
- H) Affiliate program setup
- I) Migration from another platform (Gumroad, Paddle, Stripe)
- J) Troubleshooting an issue
-
What are you selling?
- Digital product (ebook, template, software, asset)
- SaaS / subscription software
- Course or membership
- Something else
Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.
Step 2 — Route or answer directly
If the question maps to a strategy domain, route to the right skill:
| Problem domain | Route to |
|---|
| Digital product pricing, launch strategy, platform comparison | /sales-digital-products {question} |
| Checkout page optimization, upsells, order bumps, cart abandonment | /sales-checkout {question} |
| Membership site structure, course design, retention | /sales-membership {question} |
| Email marketing strategy, sequences, segmentation | /sales-email-marketing {question} |
| Affiliate program design, commission structures, recruitment | /sales-affiliate-program {question} |
| Email deliverability, SPF/DKIM/DMARC | /sales-deliverability {question} |
When routing, provide the exact command: "This is a {domain} question — run: /sales-{skill} {user's original question}"
If it's a Lemon Squeezy platform question, continue to Step 3.
Step 3 — Lemon Squeezy platform reference
Read references/platform-guide.md for the full platform reference — modules, pricing, integrations, data model, workflows, API quick-reference.
Answer the user's question using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
You no longer need the platform guide — focus on the user's specific situation.
Provide concrete next steps. If the question involves the API, reference references/lemonsqueezy-api-reference.md for endpoint details.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research — review these, especially items about plan-gated features and integration gotchas that may be outdated.
-
Account approval can take days to weeks — Lemon Squeezy requires manual account verification before you can accept live payments. Submit complete business details and identity docs upfront to speed this up. Don't plan a launch date before your account is approved.
-
Payouts can be delayed or frozen — multiple reports of payouts failing for extended periods with slow support response. Keep a financial buffer and don't rely on immediate access to funds, especially in the first few months.
-
Support is slow and AI-first — the chat support is an AI bot; human support is email-only with multi-day response times. For urgent issues, email hello@lemonsqueezy.com directly rather than using the chat widget.
-
Cloudflare can silently block webhooks — if your site uses Cloudflare, webhooks may get blocked even with IP allowlisting. Check your Cloudflare WAF rules and create an explicit allow rule for Lemon Squeezy's webhook IPs and your webhook path.
-
Stripe acquisition = uncertain roadmap — Stripe acquired Lemon Squeezy in 2024 and is building its own MoR solution (Stripe Managed Payments). Feature velocity has slowed. Evaluate whether LS's current feature set meets your needs without depending on future updates.
-
The 5% + 50¢ can climb higher — base transaction fee is 5% + 50¢, but surcharges stack: +1.5% international, +1.5% PayPal, +0.5% subscriptions, +5% abandoned-cart recovery, +3% affiliate-referred orders. Payouts also have fees (non-US bank 1%, non-US PayPal 3% capped at $30). Model your actual all-in fees before committing.
-
Email marketing is basic — built-in email is newsletters and broadcasts only. No automation workflows, no advanced segmentation, no A/B testing. For serious email marketing, connect to a dedicated ESP (Kit, Mailchimp, ActiveCampaign) via webhooks or Zapier.
Related skills
/sales-digital-products — Digital product sales strategy (pricing, launch, platform selection)/sales-checkout — Checkout optimization (upsells, order bumps, cart abandonment)/sales-merchant-of-record — Choosing a Merchant of Record / payments provider across tools (Lemon Squeezy vs Paddle vs Polar vs Creem vs Stripe; MoR vs self-managed tax)/sales-paddle — Paddle platform help (the closest MoR competitor — deepest tax coverage + B2B invoicing)/sales-membership — Membership sites and online courses/sales-email-marketing — Email marketing strategy (sequences, automation, segmentation)/sales-affiliate-program — Affiliate program design (commissions, recruitment, tracking)/sales-deliverability — Email deliverability (SPF, DKIM, DMARC, warmup)/sales-payhip — Payhip platform help (similar creator commerce platform)/sales-kit — Kit platform help (creator-first email + commerce)/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do
Examples
Example 1: Setting up a SaaS subscription
User says: "I want to sell my SaaS at $29/month and $290/year with a 14-day free trial"
Skill does: Walks through creating a product with two variants (monthly and annual), configuring trial periods, setting up the checkout overlay, and implementing webhook listeners for subscription lifecycle events (created, updated, cancelled, expired). Covers license key setup for gating software access.
Result: User has a working subscription product with trial, annual discount, and webhook integration
Example 2: Migrating from Gumroad
User says: "I'm moving my digital products from Gumroad to Lemon Squeezy — what do I need to know?"
Skill does: Compares fee structures (Gumroad 10% vs LS 5% + 50¢), explains the MoR tax handling advantage, walks through product recreation, customer migration considerations, and URL redirect strategy. Flags the account approval delay.
Result: User has a migration checklist with fee savings estimate and timeline
Example 3: Webhook integration with Next.js
User says: "My Lemon Squeezy webhooks aren't firing in production"
Skill does: Checks common causes — Cloudflare WAF blocking, incorrect webhook URL (localhost vs production), missing signature verification, SSL/TLS issues (error 525). Walks through testing with LS's test mode webhook simulation. Provides the webhook signature verification code pattern.
Result: User identifies the root cause and gets webhooks working
Troubleshooting
Webhooks not firing in production
Symptom: Webhooks work in test mode but not in production, or return 4xx/5xx errors
Cause: Cloudflare WAF blocking POST requests, incorrect webhook URL, SSL certificate issues (error 525), or missing 200 response from your endpoint
Solution: Create a Cloudflare WAF allow rule for the webhook path. Verify your webhook URL points to production (not localhost). Ensure your endpoint returns 200 within the timeout. Check Lemon Squeezy dashboard → Settings → Webhooks for delivery status and retry history. A non-200 response is re-sent up to 3 more times (4 attempts total); after that, re-send recent webhooks manually from the dashboard.
Payouts not arriving
Symptom: Sales are coming in but payouts are delayed or failing
Cause: Account verification incomplete, payout method not configured, or payout threshold not met
Solution: Check Settings → Payouts for status. Ensure identity verification and tax forms are complete. Verify your bank/PayPal payout method is correctly configured. Contact hello@lemonsqueezy.com directly for extended delays — the AI chat support cannot resolve payout issues.
License key activation failing
Symptom: Customers report "invalid license key" errors
Cause: Key status is inactive/disabled/expired, activation limit reached, or using wrong API endpoint
Solution: The License API uses a different base and rate limit (60 req/min vs 300 for main API). Check the key's status in the dashboard — expired keys need subscription renewal. Verify you're POSTing to the correct activation endpoint with Content-Type: application/x-www-form-urlencoded (not JSON:API format).
