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

Important: Third-Party Integration

Devtonic Studios created this plugin to connect WooCommerce with Lemon Squeezy (a separate payment processing company). We are not affiliated with Lemon Squeezy - we simply built the bridge that connects 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, or subscription events happen. They're essential for real-time order updates.

1

Get Your Webhook URL

  1. In plugin settings, find "Webhook URL" section
  2. Copy the displayed URL
  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

Check these only 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. 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.

1

Create Product in Lemon Squeezy

  1. Log in to Lemon Squeezy dashboard
  2. Go to Products
  3. Click "New Product"
  4. Fill in product details (name, price, description)
  5. Create variants if needed
  6. Note the Variant ID (you'll need this)
Lemon Squeezy Product Creation and Product Variant ID

Screenshot: Lemon Squeezy Product Creation and Product Variant ID

2

Copy Your Variant ID

As shown in the screenshot above, click the 3 dots menu on your product variant and select "Copy variant ID". Save this ID - you'll need it in the next step.

3

Map WooCommerce Product

  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 (shown in the screenshot below)
  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

For variable products, each variation needs its own Variant ID. Edit variations individually and add their respective Lemon Squeezy Variant IDs.

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
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
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
Webhook Errors?

If webhooks fail, verify your webhook secret is correct and your SSL certificate is valid.

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
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 automatically updated when customers complete payment.

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.

WooCommerce Blocks

Full support for new WooCommerce Blocks 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
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

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
  • Temporarily disable security plugins
  • Review webhook delivery logs in Lemon Squeezy

Product Not Found

Problem: Error about product not found

Solutions:

  • Edit product in WooCommerce
  • Check Lemon Squeezy tab has Variant ID
  • Verify variant exists in Lemon Squeezy
  • Ensure variant is active (not archived)
  • Try using "Sync Products" feature

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
Developed by Devtonic Studios • Integrates with Lemon Squeezy Payment API
Documentation Version 2.1.1 - Updated November 2025