Download the PHP package caspahouzer/lemonsqueezy-api-client without Composer

LemonSqueezy PHP API Client

A modern, PSR-4 compliant PHP API client for the LemonSqueezy platform. This package provides full coverage of all documented LemonSqueezy REST API endpoints with support for both bearer token authentication and public API access.

Features

• ✅ Full API coverage (19 resources)
• ✅ PSR-4 autoloading, PSR-7/17/18 HTTP standards compliance
• ✅ Bearer token authentication
• ✅ Public License API support
• ✅ Fluent query builder with filtering, sorting, pagination
• ✅ Automatic rate limit handling (300 req/min)
• ✅ Comprehensive exception hierarchy
• ✅ Middleware-based request pipeline
• ✅ JSON:API spec compliance
• ✅ Webhook signature verification (HMAC-SHA256 with timing-safe comparison)
• ✅ Webhook event listeners with dispatcher system
• ✅ Batch operations for efficient bulk processing
• ✅ Framework-agnostic (works with any PHP project)
• ✅ Zero production dependencies (optional Guzzle fallback)

Installation

Via Composer (Recommended)

Manual Installation

1. Download or clone this repository

2. Add PSR-4 autoloading to your composer.json:

3. Run composer dump-autoload

Quick Start

Basic Authentication

Public License API (No Authentication)

API Documentation

View Full API Documentation

The comprehensive API documentation includes:

• Class reference - Complete API reference for all public classes and methods
• Method signatures - Detailed parameter and return type documentation
• Usage examples - Code examples in class-level documentation
• Type hints - Full PSR-5 compliant type hints for PHP 8.0+
• Cross-references - Links between related classes and methods

Documentation is automatically generated and deployed to GitHub Pages on each release.

Available Resources

The client provides access to all 19 documented LemonSqueezy API resources. Note that the LemonSqueezy API has specific limitations on which operations each resource supports:

→ See docs/API_COVERAGE.md for complete endpoint checklist with all methods and accurate API capability mapping

Query Building

Use the fluent query builder for advanced filtering, sorting, and pagination:

Error Handling

The client throws specific exceptions for different error conditions:

Unsupported Operations

The LemonSqueezy API has specific limitations on which operations each resource supports. Attempting an unsupported operation will throw UnsupportedOperationException:

Note: Supported write operations are clearly marked in the docs/API_COVERAGE.md.

Special API Operations

Some resources support special action endpoints beyond standard CRUD operations:

See docs/API_COVERAGE.md for all available special operations.

Batch Operations

The client supports efficient bulk processing of resources through batch operations. Execute multiple create, update, and delete operations in a single batch with intelligent rate limiting.

Quick Start

Batch Methods

1. Create Multiple Resources

2. Update Multiple Resources

3. Delete Multiple Resources

4. Mixed Operations

Configuration Options

Handling Results

Rate Limiting

Batch operations automatically respect the API's 300 requests/minute rate limit:

• Default delay: 200ms between operations (5 ops/sec)
• Configurable via delayMs parameter
• Operations execute sequentially to ensure compliance

Advanced Configuration

Custom HTTP Client

With Logger (PSR-3)

Webhook Signature Verification

The client includes comprehensive webhook signature verification to securely validate incoming webhooks from LemonSqueezy. The verification uses HMAC-SHA256 with timing-safe comparison to prevent timing attacks.

Setup with Configuration

Method 1: Using the Client Convenience Method

The simplest approach for integration:

Method 2: Using WebhookVerifier Directly (Standalone)

For standalone use without a client instance:

Method 3: Using WebhookVerifier with Config

Method 4: Boolean Check (Non-Exception)

For cases where you prefer boolean returns:

Working with PSR-7 Streams

The verification supports PSR-7 StreamInterface for flexible webhook body handling:

Exception Handling

Different error scenarios throw specific exception codes:

Security Features

• HMAC-SHA256: Industry-standard cryptographic hash algorithm
• Timing-Safe Comparison: Uses hash_equals() to prevent timing-based attacks
• Hex Digest Format: Matches LemonSqueezy's standard webhook signature format
• Format Validation: Validates signatures are 64-character hex strings

Webhook Event Listeners

The framework includes a powerful event dispatcher system for handling webhooks. Register listeners for specific webhook events and they will be automatically executed when webhooks are received.

Quick Start

Features

• Event Dispatcher: Central hub for listener registration and event dispatch
• Closure & Class Listeners: Use closures for simple handlers or implement EventListenerInterface for complex logic
• Automatic Verification: Webhook signature is automatically verified before dispatch
• Error Resilience: Failures in one handler don't prevent others from executing
• Event Metadata: Access verification status, timestamps, and raw webhook data
• Type-Safe: Listener collections and registries prevent accidental misuse

Supported Events

All LemonSqueezy webhook events are supported:

• Orders: order.created, order.refunded
• Subscriptions: subscription.created, subscription.updated, subscription.expired, subscription.cancelled
• License Keys: license-key.created, license-key.updated, license-key.expired
• Invoices: subscription-invoice.created, subscription-invoice.paid, subscription-invoice.past-due, subscription-invoice.payment-attempt-failed, subscription-invoice.refunded

→ See docs/WEBHOOKS.md for comprehensive webhook listener documentation with examples

Examples

Using Closures:

Using Listener Classes:

Multiple Listeners for One Event:

Example: Complete Webhook Endpoint

See examples/webhook_listener.php for a complete working example.

Response Models

All responses are hydrated into model objects with convenient property accessors:

Rate Limiting

The client automatically tracks rate limits (300 requests per minute). If a rate limit is exceeded, a RateLimitException is thrown:

Testing

Requirements

• PHP >= 8.0
• PSR-18 HTTP Client (or GuzzleHttp 7.0+)
• PSR-17 HTTP Factories (or GuzzleHttp 7.0+)
• PSR-7 HTTP Messages

License

MIT. See LICENSE file for details.

Support

For issues, feature requests, or contributions, please visit the GitHub repository.

API Documentation

For complete API documentation, visit LemonSqueezy API Docs.