How to Set Up Lemon Squeezy for XFile Ultra
Lemon Squeezy is a merchant-of-record hosted checkout. XFile Ultra creates checkouts against a one-time product variant and sets the amount per cart (custom_price).
Lemon Squeezy is built-in — no premium plugin required.
Where to find it
Admin → Settings → Payment → Lemon Squeezy
1. Turn Enable Lemon Squeezy checkout on
2. Paste API key, Store ID, Variant ID, and Webhook signing secret
3. Register the webhook for order_created
4. Use Test mode while learning
5. Save settings and test on /premium
Enable for reseller (optional): shows this gateway on reseller balance top-up checkout. Member Premium upgrade and member balance top-up use the main Enable toggle only. Reseller enable needs the Reseller System premium plugin.
Fields in XFile Ultra
| Field | Setting key | From Lemon Squeezy |
|---|---|---|
| Enable | lemon_squeezy_checkout_enabled |
Main on/off |
| Enable for reseller | lemon_squeezy_checkout_reseller_enabled |
Reseller top-up |
| API key | lemon_squeezy_api_key |
Settings → API |
| Store ID | lemon_squeezy_store_id |
Numeric store id |
| Variant ID | lemon_squeezy_variant_id |
One-time variant id |
| Webhook signing secret | lemon_squeezy_webhook_secret |
Same secret as in LS webhooks |
| Test mode | lemon_squeezy_test_mode |
No live charges |
Webhook URL:
https://YOUR-DOMAIN/api/webhooks/lemon-squeezyEvent: order_created
Return (automatic): /api/checkout/lemon-squeezy/return
Env overrides: LEMON_SQUEEZY_API_KEY, LEMON_SQUEEZY_STORE_ID, LEMON_SQUEEZY_VARIANT_ID, LEMON_SQUEEZY_WEBHOOK_SECRET.
Step 1 — API key and Store ID
1. Open your Lemon Squeezy account
2. Settings → API → create an API key → copy it
3. Settings → Stores → copy the Store ID (digits only)
Official: Lemon Squeezy docs
Step 2 — Create a one-time variant
1. Create a Product for XFile Ultra checkouts
2. Add a one-time variant (not a subscription-only variant that blocks custom pricing)
3. Copy the Variant ID (not the Product ID)
XFile Ultra sets the price per checkout — the variant is the vehicle, not a fixed catalog price for every sale.
Step 3 — Webhook
Required event (must subscribe): order_created
Without that event, Lemon Squeezy can complete the order and XFile Ultra will not grant Premium / balance.
1. Lemon Squeezy → Settings → Webhooks
2. Add endpoint URL = admin webhook URL
3. Under event subscriptions / permissions, enable order_created (required)
4. Set a signing secret
5. Paste the same secret into XFile Ultra Webhook signing secret
Step 4 — Paste into XFile Ultra
1. Admin → Settings → Payment → Lemon Squeezy
2. Paste API key, Store ID, Variant ID, webhook secret
3. Turn Test mode on
4. Enable checkout → Save
5. Complete a test purchase on /premium
What is Sandbox / Test mode?
Sandbox (sometimes labeled Test mode) means you use the provider’s test environment — fake cards, fake buyers, no real money. Turn it on while learning. When you go live:
1. Turn Sandbox / Test mode off
2. Paste live keys (not test keys)
3. Register live webhooks (Stripe/PayPal have separate Test vs Live webhook endpoints)
Common problems
Wrong variant
Must be a one-time variant that supports custom pricing. Product ID ≠ Variant ID.
Webhook signature failures
Secret in Lemon Squeezy ≠ secret saved in admin. Re-copy both sides.
Paid in LS, unpaid on site
Webhook not delivered (HTTPS, firewall) or event not order_created.