Lemonsqueezy

Lemon Squeezy supports subscriptions and one-time orders via hosted checkout. Use this page when you want a simple SaaS-style checkout flow.

Configuration

<?php

return [
  'bnomei.klub.provider.handler' => \Bnomei\Klub\Provider\LemonSqueezyProvider::class,
  'bnomei.klub.providers.lemonsqueezy' => [
    'secret' => fn() => env('LEMONSQUEEZY_SECRET_KEY'),
    'webhook_secret' => fn() => env('LEMONSQUEEZY_WEBHOOK_SECRET'),
    'store_id' => fn() => env('LEMONSQUEEZY_STORE_ID'),
    'field' => 'lemonsqueezy',
  ],
];

Environment variables:

• LEMONSQUEEZY_SECRET_KEY
• LEMONSQUEEZY_WEBHOOK_SECRET
• LEMONSQUEEZY_STORE_ID

Optional provider keys:

• test_mode (true/false) to force Lemon Squeezy test mode
• checkout for provider-specific checkout payload overrides

Webhooks

Configure webhooks to POST /klub/webhooks/lemonsqueezy.

Lemon Squeezy sends the X-Signature header. Klub validates it with LEMONSQUEEZY_WEBHOOK_SECRET.

One-time purchase persistence and refunds are handled via order_created and order_refunded webhooks.

Portal and invoices

• Portal: supported (links to Lemon Squeezy orders page).
• Invoice preview: not supported.

Notes

The portal URL is the hosted orders page at https://app.lemonsqueezy.com/my-orders.

Plan data (local)

Lemon Squeezy uses local plans (providers.lemonsqueezy.plans or site plans YAML). Use at least:

• id (variant/price id)
• unit_amount (minor units)
• currency (ISO 4217)
• type (recurring or one_time, recommended for fallback mode detection)

Gotchas

• store_id is required for checkout; missing it will fail session creation.
• The portal is not customer-specific; it always links to the global orders page.

See Purchases for flow details.