Browse Plugins
DOCUMENTATION

WooCommerce Payment Gateway
Lemon Squeezy Integration

Complete step-by-step guide to integrating Lemon Squeezy payments into your WooCommerce store

Welcome!

You're about to set up the WooCommerce Lemon Squeezy Payment Gateway developed by Devtonic Studios. This plugin bridges your WooCommerce store with Lemon Squeezy's powerful payment processing API.

This guide will walk you through every step - from prerequisites to going live. Let's get started!

About This Plugin

Devtonic Studios built this plugin to connect WooCommerce with Lemon Squeezy. We are not affiliated with Lemon Squeezy. We simply built the bridge between the two platforms.

How It Works

Your WooCommerce Store

Customer shops and checks out

→

Our Plugin

Routes payment to Lemon Squeezy

→

Lemon Squeezy API

Processes the payment

Prerequisites

System Requirements

Requirement Minimum Recommended
WordPress 5.8+ Latest version
WooCommerce 6.0+ Latest version
PHP 7.4+ 8.0 or higher
SSL Certificate Required (HTTPS)
SSL Certificate is Mandatory

Lemon Squeezy requires HTTPS for webhook communication. Your site MUST have a valid SSL certificate installed before proceeding.

Step 1: Create Lemon Squeezy Account

  1. Go to lemonsqueezy.com and sign up
  2. Complete your store setup in the dashboard
  3. Verify your payment information
  4. Note your Store ID (you'll need this later)
Lemon Squeezy store id

Screenshot: Lemon Squeezy Dashboard - Store Settings ( Store ID )

Step 2: Generate API Key

  1. In Lemon Squeezy dashboard, go to Settings → API
  2. Click "Create API Key"
  3. Give it a name (e.g., "WooCommerce Integration")
  4. Copy the API key immediately (you won't see it again!)
  5. Store it securely
API Key Format: lmsq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Generate Your API Key

Screenshot: Generate Your API Key

Security Note

Keep your API key confidential. Never share it publicly or commit it to version control.

Installation

1

Upload Plugin

  1. Log in to WordPress admin
  2. Go to Plugins → Add New
  3. Click "Upload Plugin"
  4. Choose wc-lemon-squeezy.zip
  5. Click "Install Now"
  6. Click "Activate Plugin"
Lemon Squeezy Plugin Activated in WordPress

Screenshot: Lemon Squeezy Plugin Successfully Activated

2

Verify Installation

After activation, check:

  • Go to Plugins → Installed Plugins
  • Find "WooCommerce Lemon Squeezy Payment Gateway"
  • Status shows "Active"
  • No error messages appear

Configuration

1

Access Payment Settings

  1. Go to WooCommerce → Settings
  2. Click the "Payments" tab
  3. Find "Lemon Squeezy" in the list
  4. Click "Manage" (or toggle to enable)
WooCommerce Payments Tab

Screenshot: WooCommerce Payments Tab

2

Basic Settings

Configure these essential fields:

Setting What to Enter Example
Enable/Disable Check to enable ✓ Enabled
Title Name shown to customers "Credit Card"
Description Checkout description "Secure payment processing"
API Key From Prerequisites Step 2 lmsq_xxxxx...
Store ID From Prerequisites Step 1 12345
Basic Settings Configuration

Screenshot: Basic Settings Configuration

3

Enable Test Mode

For safe testing without real transactions:

  • Scroll to "Test Mode" section
  • Check "Enable Test Mode"
  • A warning banner will show on checkout
Always Test First!

Never skip test mode. Test with Lemon Squeezy's test card numbers before processing real payments.

4

Test Connection

  1. Go to WooCommerce → Lemon Squeezy in the admin menu
  2. Look for the "Quick Actions" section
  3. Click "Test Connection" button
  4. Wait for response (may take a few seconds)
  5. You should see success message with store details
Lemon Squeezy Quick Actions - Test Connection

Screenshot: WooCommerce → Lemon Squeezy - Quick Actions Section

✓ Connection Successful! Store ID: 12345 Store Name: Your Store Name API Status: Active
Connection Failed?

Double-check your API Key and Store ID for typos. Ensure no extra spaces. Verify SSL certificate is valid.

5

Save Settings

  • Review all settings carefully
  • Click "Save Changes"
  • Wait for success confirmation

Webhook Setup

What are Webhooks?

Webhooks notify your store instantly when payments are processed, refunds occur, subscription events happen, or license keys are generated. They're essential for real-time order updates.

Option A: Automatic Registration (Recommended)

The easiest way to set up your webhook - one click and the plugin does everything for you.

1

Auto-Register Webhook

  1. Go to WooCommerce → Lemon Squeezy in the admin menu
  2. Find the "Webhook Setup" card
  3. Click "Register Webhook on Lemon Squeezy"
  4. The plugin will automatically:
    • Create the webhook endpoint on Lemon Squeezy
    • Subscribe to all necessary events
    • Store the signing secret in your settings
  5. You should see a success message confirming registration
Auto Register Webhook Button in Webhook Setup Card

Screenshot: Click "Register Webhook on Lemon Squeezy" - one click sets up everything

That's It!

Auto-registration handles everything. No need to copy URLs or secrets between dashboards. You can skip to the Product Mapping section.

Option B: Manual Setup

If auto-registration doesn't work or you prefer manual control, follow these steps instead.

1

Get Your Webhook URL

  1. In the plugin settings, find the "Webhook Setup" card
  2. Copy the Webhook URL displayed
  3. It looks like: https://yoursite.com/wp-json/wc-lemon-squeezy/v1/webhook
https://yoursite.com/wp-json/wc-lemon-squeezy/v1/webhook
Get Your Webhook URL

Screenshot: Get Your Webhook URL from WordPress Site

2

Add Webhook in Lemon Squeezy

  1. Go to Lemon Squeezy dashboard
  2. Navigate to Settings → Webhooks
  3. Click "Add Endpoint"
  4. Paste your webhook URL
  5. Select events based on what you're selling:
Select Events Based on Your Products

Only check the events that match the type of products you're selling. Don't select subscription events if you only sell one-time purchases, and vice versa.

Required for All Stores:

order_created
order_refunded

If You Sell Products With License Keys:

license_key_created
license_key_updated

If You Sell Subscriptions:

subscription_created
subscription_updated
subscription_cancelled
subscription_resumed
subscription_expired
subscription_paused
subscription_unpaused
subscription_payment_success
subscription_payment_failed
subscription_payment_recovered
Lemon Squeezy Webhook Configuration

Screenshot: Lemon Squeezy Webhook Configuration

3

Copy Webhook Secret

  1. After saving webhook in Lemon Squeezy
  2. Copy the "Signing Secret"
  3. Return to WordPress plugin settings
  4. Paste it in "Webhook Secret" field
  5. Save settings
Security Critical!

The webhook secret validates that requests are genuinely from Lemon Squeezy. Every incoming webhook is verified using HMAC signatures. Never skip this step!

Product Mapping

What is Product Mapping?

Each WooCommerce product must be linked to a Lemon Squeezy product variant. This tells the plugin which Lemon Squeezy product to charge for each item.

Option A: One-Click Product Sync (Recommended)

The fastest way to connect your products - the plugin pulls everything from Lemon Squeezy automatically.

1

Sync Products From Lemon Squeezy

  1. Go to WooCommerce → Lemon Squeezy in the admin menu
  2. Find the "Quick Actions" section
  3. Click "Sync Now" next to Sync Products
  4. The plugin pulls all your products and variants from Lemon Squeezy
  5. You'll see a success message like: "6 products and 8 variants synced successfully"
Product Sync Button in Quick Actions

Screenshot: Click "Sync Now" to pull all products from Lemon Squeezy

2

Map to WooCommerce Products

After syncing, the plugin replaces the manual Variant ID text field with a dropdown on every product.

For Simple Products:

  1. Go to Products → All Products
  2. Click to edit any product
  3. Scroll down to Product Data → General tab
  4. You'll see a "Lemon Squeezy Variant" dropdown
  5. The dropdown lists all your LS products and variants with names and prices - e.g., "Lemon Squeezy for WooCommerce: Yearly - $39.00 (ID: 48291)"
  6. Select the matching variant and click "Update"
Lemon Squeezy Variant Dropdown on Product Edit Page

Screenshot: Select your Lemon Squeezy variant from the dropdown on the General tab

For Variable Products:

  1. Edit the variable product
  2. Go to Product Data → Variations
  3. Expand any variation
  4. You'll see an "LS Variant" dropdown on each variation
  5. Select the matching Lemon Squeezy variant for each variation
LS Variant Dropdown on Product Variation

Screenshot: Each variation has its own "LS Variant" dropdown

No dropdown? Sync your products first. Go to WooCommerce → Lemon Squeezy and click Sync Now.

Fallback logic: If a variation doesn't have its own variant set, the plugin uses the parent product's variant from the General tab.

Option B: Manual Product Mapping

If you prefer to map products manually, follow these steps.

1

Get Variant ID From Lemon Squeezy

  1. Log in to Lemon Squeezy dashboard
  2. Go to Products
  3. Click the 3 dots menu on your product variant
  4. Select "Copy variant ID"
Lemon Squeezy Product Creation and Product Variant ID

Screenshot: Lemon Squeezy Product Creation and Product Variant ID

2

Paste Variant ID in WooCommerce

  1. In WordPress, go to Products → All Products
  2. Click to edit a product
  3. Scroll down to the "Product Data" section
  4. Look for the "Lemon Squeezy Variant ID" field
  5. Paste your Variant ID in this field
  6. Click "Update" to save
  7. Repeat for all products
WooCommerce Product Edit - Lemon Squeezy Variant ID Field

Screenshot: Paste Your Variant ID in the Product Data Section

Variable products? Each variation has its own Variant ID field. Edit variations individually and paste the matching ID. If a variation has no ID, the plugin falls back to the parent product's ID.

Checkout Modes

The plugin supports two checkout modes. You can switch between them anytime in settings.

1

Overlay Mode (Recommended)

Checkout opens as a popup directly on your site. Customers never leave your page - they pay inside the overlay, it closes, and they're back on your store.

  • Better conversion - customers stay on your site
  • Supports dark mode, store logo, and product image customization
  • Uses Lemon Squeezy's Lemon.js script to open the checkout popup
  • Falls back to a redirect link if the overlay can't open
2

Redirect Mode

Customers are sent to Lemon Squeezy's hosted checkout page. They pay there and get redirected back to your store when they're done.

  • Simpler - no popup, standard redirect flow
  • Works the same on the backend (same webhooks, same order updates)
  • Good option if your theme conflicts with the overlay
3

How to Change Checkout Mode

  1. Go to WooCommerce → Settings → Payments → Lemon Squeezy → Manage
  2. Find the "Checkout Mode" dropdown
  3. Select "Overlay" or "Redirect"
  4. Click "Save Changes"
Checkout Mode Dropdown - Overlay vs Redirect

Screenshot: Checkout Mode setting - choose Overlay or Redirect

Checkout Customization

The plugin has three toggle settings that control how the Lemon Squeezy checkout page looks. These settings work with both overlay and redirect mode.

Setting What It Does Default
Dark Mode Checkout Switches the checkout to a dark theme Off
Show Store Logo Displays your store logo on the checkout page On
Show Product Image Displays the product image during checkout On

All three settings are simple checkboxes found in the plugin settings under WooCommerce → Settings → Payments → Lemon Squeezy → Manage.

License Key Delivery

If your Lemon Squeezy products generate license keys, the plugin captures them automatically via webhook and stores them on the WooCommerce order.

What Gets Stored

When Lemon Squeezy generates a license key for a sale, the plugin stores the following on the WooCommerce order:

  • License Key - The actual key (e.g., A8F2-K9D1-M3P7-X6B4)
  • Status - Active, inactive, expired, etc.
  • Activation Limit - How many activations are allowed
  • Expiry Date - When the license expires

Where Customers See Their License Key

  • Order Detail Page - In the customer's My Account → Orders → View Order page, a "License Key" section appears with the key, status, activation limit, and expiry
  • Order Emails - The license key is automatically included in WooCommerce order confirmation and completion emails
  • Admin Order Page - You can view all license details in the order meta within the WordPress admin
Webhook Events Required

Make sure you have license_key_created and license_key_updated webhook events enabled (the auto-register option handles this for you). When a key is updated on Lemon Squeezy's side, the plugin updates the stored data on the WooCommerce order automatically.

Subscriptions

The plugin handles the full subscription lifecycle. All subscription events from Lemon Squeezy sync automatically to your WooCommerce orders.

Supported Subscription Events

The plugin handles all of these subscription events via webhooks:

subscription_created
subscription_updated
subscription_cancelled
subscription_paused
subscription_unpaused
subscription_resumed
subscription_expired
subscription_payment_success
subscription_payment_failed
subscription_payment_recovered

What Gets Stored on the Order

When a subscription is created or updated, the plugin stores the following on the WooCommerce order: subscription ID, status, product/plan name, renewal date, end date, trial end date, payment method (card brand + last 4 digits), and pause details if applicable.

Customer Self-Service

Customers can manage their subscriptions directly from their WooCommerce My Account page:

  • "Manage Subscription" button - Links to the Lemon Squeezy customer portal where they can cancel, upgrade, or modify their subscription
  • "Update Payment Method" button - Links to the Lemon Squeezy payment update page
  • Subscription Details table - Shows plan name, status, next renewal date, access expiry, and payment method on the order detail page
No Extra Plugin Needed

You don't need WooCommerce Subscriptions or any other subscription plugin. This plugin handles subscription lifecycle events directly via Lemon Squeezy webhooks.

Discount Codes

You can set a Lemon Squeezy discount code in the plugin settings to apply automatically to every checkout.

How to Set It Up

  1. First, create a discount code in your Lemon Squeezy dashboard
  2. Go to WooCommerce → Settings → Payments → Lemon Squeezy → Manage
  3. Find the "Default Discount Code" field
  4. Paste the discount code from Lemon Squeezy
  5. Click "Save Changes"

The discount code will now be applied to every checkout session automatically. Customers will see the discounted price on the Lemon Squeezy checkout page.

Tip

This field is optional. Leave it empty if you don't want a default discount. You can always change or remove it later.

Testing

Never Skip Testing!

Always test thoroughly before processing real customer payments. This prevents payment issues and customer frustration.

1

Verify Test Mode is Enabled

  • Ensure test mode is checked in settings
  • Visit your store's checkout
  • You should see a test mode warning banner
2

Place Test Order

  1. Visit your store front-end
  2. Add a product to cart (one with mapped Variant ID)
  3. Go to checkout
  4. Fill in test billing info
  5. Select "Lemon Squeezy" payment method
  6. Use test card:

Test Card Numbers

Card: 4242 4242 4242 4242 Expiry: Any future date CVC: Any 3 digits ZIP: Any 5 digits
Test Both Checkout Modes

If you plan to use overlay mode, test it separately. Try switching between overlay and redirect mode to make sure both work correctly with your theme.

3

Verify Order

  1. Go to WooCommerce → Orders
  2. Find your test order
  3. Status should be "Processing" or "Completed"
  4. Check order notes for transaction details
  5. Verify payment recorded correctly
  6. If your product generates a license key, check that it appears in the order metadata
4

Test Webhooks

  1. Enable debug logging in plugin settings
  2. Place another test order
  3. Go to WooCommerce → Status → Logs
  4. Select "wc-lemon-squeezy" log file
  5. Look for webhook events:
    • order_created
    • Payment success
    • Signature validation success
    • license_key_created (if applicable)
Webhook Errors?

If webhooks fail, verify your webhook secret is correct and your SSL certificate is valid. If you used auto-registration, try re-registering the webhook.

5

Test Refunds (Optional)

  1. Open completed test order
  2. Click "Refund" button
  3. Enter refund amount
  4. Click "Refund via Lemon Squeezy"
  5. Check order notes for confirmation
  6. Verify refund appears in Lemon Squeezy dashboard

Going Live

1

Pre-Launch Checklist

  • ✓ Test mode orders completed successfully
  • ✓ Webhooks working (check logs)
  • ✓ All products have Variant IDs mapped
  • ✓ SSL certificate valid
  • ✓ Refund testing successful
  • ✓ Checkout mode chosen (overlay or redirect)
  • ✓ License keys appearing on orders (if applicable)
2

Disable Test Mode

  1. Go to plugin settings
  2. Uncheck "Enable Test Mode"
  3. Double-check API credentials are for LIVE mode
  4. Save changes
Important!

Ensure your API key and webhook secret are for LIVE mode, not test mode. Check Lemon Squeezy dashboard to confirm.

3

Final Test with Real Card

  1. Place one order with real card
  2. Use small amount (or a free product)
  3. Verify order processes correctly
  4. Process immediate refund if needed
  5. Monitor first 5-10 orders closely
4

Monitor Initial Orders

  • Keep debug logging enabled initially
  • Check order status after each sale
  • Verify webhooks firing correctly
  • Watch for any error patterns
  • Disable debug logging after 1 week if stable

You're Live!

Congratulations! Your WooCommerce store is now accepting payments through Lemon Squeezy. Monitor your orders and reach out if you need any support.

Features

Secure Processing

HMAC signature validation on all webhooks, encrypted API communication, and PCI-compliant payment handling.

Real-Time Sync

Instant order updates via webhooks. Orders, subscriptions, and license keys all update automatically.

Easy Refunds

Process full and partial refunds directly from WooCommerce admin with automatic sync to Lemon Squeezy.

Test Mode

Safe testing environment with visual indicators. Test entire payment flow without real transactions.

Debug Logging

Comprehensive logging tracks all API calls, webhook events, and errors for easy troubleshooting.

Block & Classic Checkout

Full support for both WooCommerce Block-based checkout and classic checkout for maximum compatibility.

Processing Refunds

How to Refund

  1. Go to WooCommerce → Orders
  2. Open the order you want to refund
  3. Click "Refund" button
  4. Enter refund amount (full or partial)
  5. Click "Refund via Lemon Squeezy"
  6. Wait for confirmation in order notes

The plugin handles the refund on both WooCommerce and Lemon Squeezy. You don't need to process it separately in the LS dashboard.

Refund Processing Time

Refunds are processed immediately through the API. Customer sees refund in 5-10 business days depending on their bank.

Refund Requirements

  • Original payment must be through Lemon Squeezy
  • API key must have refund permissions
  • Refund amount can't exceed original payment
  • Partial refunds supported

Developer Hooks

The plugin provides action hooks and filter hooks for developers who need to run custom code when events happen or modify plugin behavior.

Action Hooks

These fire after the plugin processes a webhook event. Use them to run custom code - like syncing data to a CRM, sending custom notifications, or updating external systems.

wcls_order_created wcls_order_refunded wcls_subscription_created wcls_subscription_updated wcls_subscription_cancelled wcls_subscription_paused wcls_subscription_unpaused wcls_subscription_resumed wcls_subscription_expired wcls_subscription_payment_success wcls_subscription_payment_failed wcls_subscription_payment_recovered wcls_license_key_created wcls_license_key_updated

All action hooks receive three parameters: $order (WooCommerce order object), $event_data (Lemon Squeezy event data), and $full_payload (complete webhook payload). The license key hooks receive $order, $license_key (or $event_data), and $event_data.

Filter Hooks

Use these to customize plugin behavior without editing plugin files.

Filter What It Does Default
wcls_button_color Change the checkout button color #7C3AED
wcls_is_available Control when the payment gateway shows up true (when enabled)
wcls_icon Swap the gateway icon shown at checkout Credit card icons
wcls_checkout_expiry_seconds How long checkout URLs stay valid 1800 (30 minutes)
wcls_default_variant_id Set a fallback variant ID when none is configured Empty string

Troubleshooting

Connection Test Failed

Problem: Connection test returns an error

Solutions:

  • Verify API Key copied correctly (no spaces)
  • Check Store ID is correct
  • Ensure SSL certificate is valid
  • Check server can make HTTPS requests
  • Try regenerating API key in Lemon Squeezy

Payment Not Processing

Problem: Order stays pending after checkout

Solutions:

  • Check product has Variant ID mapped
  • Enable debug logging and check logs
  • Verify webhook configured correctly
  • Check webhook secret matches
  • Ensure webhook URL accessible

Webhooks Not Working

Problem: Orders not updating automatically

Solutions:

  • Test webhook from Lemon Squeezy dashboard
  • Verify webhook secret matches
  • Check SSL certificate valid
  • Ensure REST API not blocked by security plugins
  • Temporarily disable security plugins to test
  • Review webhook delivery logs in Lemon Squeezy
  • Try re-registering webhook using the auto-register button

Overlay Checkout Not Opening

Problem: Popup doesn't appear in overlay mode

Solutions:

  • Check browser console for JavaScript errors
  • Verify no ad-blocker is blocking lemonsqueezy.com scripts
  • Try a different browser to rule out extensions
  • Check for theme or plugin JavaScript conflicts
  • Switch to redirect mode as a fallback
  • The plugin shows a fallback link if the overlay can't open

License Key Not Appearing

Problem: License key not showing on order

Solutions:

  • Verify license_key_created webhook event is enabled
  • Check that the product in Lemon Squeezy has license key generation turned on
  • Look at debug logs for the license key webhook event
  • Ensure the WooCommerce order ID is being passed correctly to LS

Product Not Found

Problem: Error about product not found

Solutions:

  • Edit product in WooCommerce
  • Check the Lemon Squeezy Variant ID field has a value
  • Verify variant exists in Lemon Squeezy and is not archived
  • Try using the "Sync Products" feature to refresh
  • For variable products, check each variation has its own Variant ID

Refund Failed

Problem: Cannot process refund

Solutions:

  • Verify payment was through Lemon Squeezy
  • Check API key has refund permissions
  • Ensure order has Lemon Squeezy order ID
  • Check debug logs for error details
  • Try refund in Lemon Squeezy dashboard directly
Still Need Help?

Enable debug logging, reproduce the issue, and check logs at WooCommerce → Status → Logs. Then contact support with log excerpts.

Support

Plugin Support

Devtonic Studios

For plugin issues, configuration help, product mapping, or technical problems:

Email Plugin Support

Payment Platform Support

Lemon Squeezy

For Lemon Squeezy account issues, fees, payouts, or their platform:

Lemon Squeezy Help
Before Contacting Support

Please enable debug logging, reproduce the issue, and check logs at WooCommerce → Status → Logs. Include relevant log excerpts when contacting support.

Ready to Accept Payments?

Follow this guide step-by-step and you'll be processing payments in no time.

Start Setup Contact Support

WooCommerce Lemon Squeezy Integration Plugin v2.0
Developed by Devtonic Studios • Integrates with Lemon Squeezy Payment API
Documentation Version 3.0.0