OpenParable
Skip to content
← Back to skills

Lemon Squeezy Integration

Apps & Automation
lemon-squeezy-integration

Lemon Squeezy Integration is an Agent Skill for apps & automation published in the pockethost/pockethost repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Full Lemon Squeezy integration — REST API, @lemonsqueezy/lemonsqueezy.js server SDK, Lemon.js checkout overlays, webhooks, custom_data, and subscriptions. Use when integrating Lemon Squeezy billing, checkout, webhooks, LS API, Lemon.js, or subscription provisioning into an application.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/pockethost/pockethost/blob/HEAD/.cursor/skills/lemon-squeezy-integration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/lemon-squeezy-integration, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Lemon Squeezy Integration

Official docs: https://docs.lemonsqueezy.com/

Architecture

Three layers — use all three for a production SaaS integration:

LayerToolRuns on
Checkout UXLemon.js + checkout URLsBrowser
Admin / dynamic checkoutREST API or @lemonsqueezy/lemonsqueezy.jsServer only
ProvisioningWebhooksServer endpoint

Never expose LEMONSQUEEZY_API_KEY in client code. The npm SDK is server-only.

Golden rule: Webhooks are the source of truth for granting access. Lemon.js Checkout.Success is UX-only — do not provision solely from client events.

Choose an approach

NeedUse
Static pricing pageDashboard checkout URLs + optional Lemon.js overlay
Per-user checkout with custom dataAppend checkout[custom][user_id] to URL, or create checkout via API
Dynamic pricing / on-demand checkoutServer: createCheckout → open URL with Lemon.js
Grant/revoke access after paymentWebhook handler
Customer billing portalsubscription.urls.update_payment_method from API + Lemon.js overlay

Required environment variables

VariablePurpose
LEMONSQUEEZY_API_KEYServer API auth (Settings → API)
LEMONSQUEEZY_STORE_IDStore ID for checkout creation
LEMONSQUEEZY_WEBHOOK_SECRETVerify incoming webhook X-Signature

Use test mode keys until production. Docs: https://docs.lemonsqueezy.com/help/getting-started/test-mode

End-to-end workflow

1. Store setup

Create products and variants in the LS dashboard (or sync via API). Record store_id, product_id, and variant_id for each plan.

2. Checkout

Static URL:

https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]

With user linking (required for webhook provisioning):

?checkout[custom][user_id]=USER_ID&checkout[email][email protected]

Overlay: Load Lemon.js, add lemonsqueezy-button class to links, or call LemonSqueezy.Url.Open(url).

Dynamic: Server creates checkout via API/SDK → use data.attributes.url from response.

Share /checkout/buy/ URLs only. Do not share converted /checkout/?cart= URLs — they are single-use per customer.

PocketHost uses custom domain URLs like https://store.pockethost.io/buy/... — see pockethost.md.

3. Webhook endpoint

  1. Register URL in Settings → Webhooks (or via API)
  2. Verify HMAC-SHA256 of the raw request body against X-Signature header
  3. Read meta.event_name and meta.custom_data
  4. Update your database idempotently
  5. Return 200 quickly

Key events: order_created, subscription_created, subscription_updated, subscription_expired, subscription_cancelled, order_refunded, subscription_payment_refunded

4. Persist subscription state

Store at minimum: LS subscription/order id, status, variant_id, renews_at, ends_at, and your internal plan tier mapping.

On refund/expiry/cancel → revoke or decrement access.

Common tasks

Add a new plan

  1. Create variant in LS dashboard
  2. Add checkout URL to frontend (with checkout[custom][user_id])
  3. Add {product_id}-{variant_id} to webhook allowlist and product handler map
  4. Map variant → internal subscription fields

Debug a failed webhook

  1. Confirm webhook URL and signing secret match env
  2. Check LS dashboard webhook log for payload and response
  3. Verify signature uses raw body (not re-serialized JSON)
  4. Confirm meta.custom_data.user_id was passed at checkout
  5. Confirm product/variant ID is in your handler allowlist

Reference files