Laravel Laravel Package

Technical Evaluation

Architecture fit

• Thin, idiomatic Laravel SDK over the Lemon Squeezy REST API: service provider, facade, publishable config and migrations, a Billable-style trait, events, and a webhook entry point. It sits at the edge of the domain rather than in the core.
• Good fit for a standard Laravel monolith or modular monolith where billing is a bounded context. Poor fit if billing logic is deeply entangled with entitlements, metering, or custom proration — the package exposes vendor semantics (subscription statuses, license keys, checkout URLs) that will leak into your models unless you wrap it.
• Lemon Squeezy is a merchant of record, so tax/VAT and payment-method handling are offloaded. That is an architectural simplification, but it also means payout timing, refunds, and customer communication are constrained by the vendor.

Integration feasibility

• Composer install, publish config/migrations, set API key and webhook signing secret, expose a webhook route, run a queue worker. A competent Laravel developer reaches a working sandbox checkout in 1–2 days.
• Main friction points: mapping LS subscriptions onto an existing users/teams/tenancy model; reconciling local entitlement state with LS as source of truth; ensuring the webhook route bypasses CSRF and is reachable in all environments; test-mode vs live-mode configuration isolation.
• The package is a convenience layer, not a billing engine. Anything beyond the happy path (idempotency, retries, reconciliation, dunning) is our responsibility.
• Release 1.9.0 improves installability by removing pcntl from required packages and broadens compatibility to PHP 8.5 and Laravel 13. This lowers environment friction, particularly in containers or platforms where pcntl is absent or undesirable.

Technical risk

• Revenue-critical dependency on a single external SaaS plus a small MIT package with no SLA. Adoption remains narrow — limited community battle-testing, fewer answers when edge cases appear.
• Release 1.9.0 is a positive maintenance signal: PHP 8.5 support, Laravel 13 support, a regex fix for the expose listen command, and three first-time contributors. The release cadence and compatibility work reduce the earlier concern about stale or forward-dated metadata, but we should still verify the supported Laravel/PHP matrix on Packagist and GitHub before committing.
• Webhook delivery is at-least-once and can arrive out of order. Without an idempotency store and state machine, duplicate or stale events will corrupt entitlements.
• Vendor lock-in is real but bounded: the API surface is small, so an exit to Stripe/Cashier or Paddle is feasible if we keep the package behind our own interface. Migrating existing subscribers is the expensive part, not the code.
• The low opportunity score (25.79) and composite score (18.06) suggest this is a niche integration rather than a platform bet — appropriate for a cost-conscious launch, not for a business where billing is a differentiator.

Key questions

• Which Laravel and PHP versions are supported today? Release 1.9.0 adds PHP 8.5 and Laravel 13, but we must confirm our exact versions and the maintainer's upgrade track record across majors.
• Does the package handle webhook signature verification and idempotency, or must we build both?
• Who is authoritative for subscription state — LS or our database — and what is the reconciliation policy?
• Do we need license keys, checkout overlays, and customer portal, or only subscriptions? Scope drives how much vendor surface we absorb.
• What is our exposure if LS has an outage, changes API versions, or raises pricing? Is there a contractual or technical exit path?
• Multi-tenant? Multi-currency? PII in webhook payloads and retention obligations?
• Who owns the webhook endpoint operationally, and what is the on-call story for billing incidents?

Integration Approach

Stack fit

• Standard Composer package for Laravel; fits a queue-backed stack (Redis + Horizon), works under Octane, and has no frontend opinion — checkout is typically a hosted LS page. Release 1.9.0 explicitly supports Laravel 13 and PHP 8.5 and removes the pcntl requirement, widening compatibility. Confirm compatibility with our Laravel version, PHP version, and any tenancy/auth packages before adoption.
• Check for conflicts with laravel/cashier if we are dual-running, and for route/middleware collisions on the webhook path.

Migration path

• Greenfield: low-risk, ship behind a feature flag and treat LS as system of record for payment state, our DB as system of record for entitlements derived from it.
• From Stripe/Cashier: not a drop-in. Object models, event names, and proration behavior differ. Plan a translation layer, a dual-run period, and accept that existing subscribers likely need to re-checkout or be migrated with vendor assistance. Budget for this explicitly; it is the largest cost in the project.

Compatibility

• Pin the package version — likely 1.9.0 if we are on or near Laravel 13 / PHP 8.5 — and record the supported Laravel/PHP matrix in the ADR. Validate against our actual database (MySQL vs Postgres), tenancy model, and auth guard. Verify webhook route registration does not clash with existing routes and that CSRF exceptions are scoped. The pcntl removal should simplify installation in restricted environments, but confirm no runtime features depended on it.

Sequencing

1. Sandbox spike with a test product and test card; confirm checkout, webhook receipt, and cancellation end to end.
2. Define our internal billing domain events and subscription state machine first; the package is an adapter behind that interface.
3. Implement webhook endpoint with signature verification, idempotency key store, and queued processing.
4. Add a scheduled reconciliation job comparing LS subscriptions to local state.
5. Wire entitlements to the internal interface, not directly to package models.
6. Staged rollout by cohort behind a flag; keep the legacy path live until two clean billing cycles pass.
7. Publish runbook, dashboards, and alerts before removing the fallback.

Operational Impact

Maintenance

• Small code footprint, but we inherit LS API versioning and webhook schema drift. Budget roughly 0.1–0.2 FTE for dependency upgrades, Laravel major-version bumps, and event-shape changes. Pin versions and review release notes on a schedule rather than reactively.
• Release 1.9.0 shows active maintenance and broader framework support; this reduces — but does not eliminate — the risk of sporadic release cadence. Track upstream issues and be prepared to self-patch or fork if a critical Laravel/PHP compatibility gap appears.

Support

• Documentation plus GitHub issues; no commercial SLA from the package maintainers. Billing incidents escalate to Lemon Squeezy support, not the package. The community remains small, though 1.9.0 added new contributors. Plan for internal ownership rather than relying on community support.

Scaling

• Webhook volume is modest for most SaaS products; a queue and Horizon absorb it comfortably. Watch growth of the idempotency table and write amplification on subscription updates.
• LS-side API rate limits matter for checkout creation and license validation at peak. Hosted checkout removes PCI scope and most traffic spikes from our infrastructure.

Failure modes

• Missed, duplicated, or out-of-order webhooks → incorrect entitlements. Needs idempotency keys, ordering guards, and a reconciliation job.
• Signing-secret rotation or misconfiguration → silent webhook rejection; alert on 4xx rate at the endpoint.
• LS outage blocks new purchases; existing access must survive because local state is authoritative for entitlements.
• Refunds and chargebacks not reflected → revenue leakage and access drift; reconcile against LS payouts monthly.
• Sandbox/live key and webhook mixups → test events hitting production. Enforce separate environments and refuse live mode in non-prod.
• Expired API keys and rotated secrets → checkout failures; monitor proactively.

Ramp-up

• 1–2 days for a Laravel developer to reach a demo-quality integration; 1–2 weeks to make it production-grade with idempotency, reconciliation, observability, and runbooks. Insist on the latter scope.
• The hidden cost is billing domain knowledge — merchant-of-record mechanics, VAT, dunning, refunds — not the package API. Assign a named owner and document the state machine; otherwise every billing question becomes an incident.