LemonSqueezy Integration for SaaS Subscriptions

LemonSqueezy Integration for SaaS Subscriptions

LemonSqueezy is Merchant of Record platform, Paddle analog, but targeted at indie developers and small SaaS products. Takes care of taxes, refunds, fraud detection. Suitable for early-stage products without resources for full billing. Commission — 5% + 50¢ on free plan, 3.5% + 30¢ on Lemon.js Plus.

Integration takes 1–3 working days.

SDK and Setup

LemonSqueezy provides official SDKs for JavaScript/TypeScript and PHP:

npm install @lemonsqueezy/lemonsqueezy.js
composer require lmsqueezy/laravel

Laravel package (lmsqueezy/laravel) adds Billable trait to User model, similar to Laravel Cashier:

use LemonSqueezy\Laravel\Billable;

class User extends Authenticatable
{
    use Billable;
}

Creating Variant for Subscription

In LemonSqueezy product → variant (analogous to Price in Stripe). Variants created in dashboard. For subscription billing interval and trial period specified.

Checkout

// Generate checkout URL
$checkout = $user->checkout('variant_id_here', [
    'checkout_options' => [
        'dark'           => true,
        'button_color'   => '#7C3AED',
        'subscription_preview' => true,
    ],
    'checkout_data'    => [
        'email'       => $user->email,
        'name'        => $user->name,
        'custom'      => ['user_id' => $user->id],
    ],
    'expires_at'       => now()->addHours(24)->toIso8601String(),
]);

return redirect($checkout->url);

Checkout opens as overlay or separate page on checkout.lemonsqueezy.com. Custom domain only on paid plan.

Webhook

// routes/web.php
Route::lemonSqueezyWebhooks('/lemon-squeezy/webhook');

Package automatically verifies signature and dispatches Laravel events:

use LemonSqueezy\Laravel\Events\SubscriptionCreated;
use LemonSqueezy\Laravel\Events\SubscriptionUpdated;
use LemonSqueezy\Laravel\Events\SubscriptionExpired;
use LemonSqueezy\Laravel\Events\OrderRefunded;

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        SubscriptionCreated::class => [ActivateUserSubscription::class],
        SubscriptionExpired::class => [DeactivateUserSubscription::class],
        OrderRefunded::class       => [HandleRefund::class],
    ];
}

Activation listener:

class ActivateUserSubscription
{
    public function handle(SubscriptionCreated $event): void
    {
        $userId = $event->subscription->custom_data['user_id'] ?? null;
        if (!$userId) return;

        $user = User::find($userId);
        $user?->update([
            'plan'            => $event->subscription->product_name,
            'subscribed_at'   => now(),
            'subscription_status' => 'active',
        ]);
    }
}

Subscription Management

// Get user subscription
$subscription = $user->subscription();

// Cancel (end of period)
$subscription->cancel();

// Immediate cancellation
$subscription->cancelNow();

// Resume cancelled subscription
$subscription->resume();

// Check status
if ($user->subscribed()) {
    // Active subscription
}

if ($user->onTrial()) {
    $trialEndsAt = $user->trialEndsAt();
}

Customer Portal

LemonSqueezy generates customer portal link:

$portalUrl = $user->customerPortalUrl();
return redirect($portalUrl);

Portal allows changing card, downloading invoices, cancelling subscription. Customization limited.

Licenses (One-Time Products)

LemonSqueezy supports not only subscriptions but license keys for one-time products. On purchase license key generated, can be activated via API:

// Activate license key
$response = Http::withToken(config('lemon-squeezy.api_key'))
    ->post('https://api.lemonsqueezy.com/v1/licenses/activate', [
        'license_key'  => $request->license_key,
        'instance_name'=> $request->app_name,
    ]);

if ($response->json('activated')) {
    $user->update(['license_key' => $request->license_key, 'is_licensed' => true]);
}

Limitations

LemonSqueezy doesn't support metered/usage-based billing — only fixed amounts. For SaaS with consumption-based pricing Stripe Billing or Orb better. Also no B2B invoicing with payment delay. For simple SaaS products with fixed plans — sufficient enough.