Lemon Squeezy Integration Skill

This skill provides a "Pro-Grade" pattern for implementing Lemon Squeezy with Next.js and Supabase, focusing on secure checkout, granular webhook sync, and proper subscription lifecycle management.

Workflows

1. Initialization

Proper setup requires both apiKey initialization and STORE_ID configuration.

• See setup.md for environment variable requirements and initialization patterns.

2. Checkout & User Tracking

Always pass user_id in custom_data to ensure the webhook can link the purchase to the correct Supabase user.

• See checkout.md for creating checkout sessions.

3. Webhook Handling

Secure implementation requires signature verification and idempotent event processing.

• See webhooks.md for the "Verify, Log, Process" pattern.

4. Subscription Management

Handle plan changes (upgrades/downgrades) and reactivation while keeping usage limits in sync.

• See subscriptions.md for transition logic.

5. Usage Tracking Integration

Sync payment events to product usage limits (e.g., reset prompts on renewal, upgrade limits on plan change).

• See usage-sync.md for the "UsageService" pattern.

Resources

• Schema: See schema.sql for the recommended subscriptions table structure.
• Webhook Template: Use the patterns in webhooks.md to build a robust endpoint.

Guidelines

• Security: Never expose the Service Role key or Lemon Squeezy API keys to the client.
• Sync: Always log the raw webhook payload before processing to allow for replay/debugging.
• Downgrades: Prefer "pending downgrade" logic (effective at renewal) over immediate cancellations to avoid data loss.