Laravel Bachs

An independent, community-maintained Laravel integration for Bachs.io.

Introduction

Laravel Bachs brings Bachs.io billing to Laravel: products, customers, subscriptions, checkout sessions, payments, refunds, payment methods, webhooks, and more — with a Cashier-style API that fits naturally into your application.

Requires PHP ^8.2 and Laravel ^12.0|^13.0. See CHANGELOG.md for the latest changes.

Features

• Products & product groups — create, list, update, archive/unarchive.
• Customers — create, list, update, and portal sessions.
• Billable trait — attach billing to any Eloquent model with createAsBachsCustomer(), checkout(), subscribeTo(), subscribed(), cancel(), resume(), and billingPortalUrl().
• Checkout sessions — hosted redirects and inline overlay modals.
• Subscriptions — list, get, update, cancel with status helpers.
• Payments & refunds — list, get, refund with status helpers.
• Payment methods — list and payment rail lookup.
• Currencies & balances — supported currencies and balance queries.
• Media uploads — multipart upload support with validation.
• Webhooks — signature verification, typed events, queue-safe processing, idempotency, optional persistence, and automatic local model sync.
• Blade components — <x-bachs::checkout>, <x-bachs::checkout-overlay>, and <x-bachs::subscribe>.
• Artisan commands — bachs:install, bachs:health, and webhook management.
• Local models — opt-in database mirrors for customers, products, payments, and subscriptions synced via webhooks.
• Multi-connection — talk to multiple Bachs accounts from one application.
• Typed exceptions — every error maps to a specific PHP exception class.

Requirements

• PHP ^8.2
• Laravel ^12.0|^13.0

Installation

The package registers its own service provider automatically. Run the install command to publish config, migrations, and views:

Or publish individually:

Configuration

Set your credentials in .env:

• BACHS_ENV selects the sandbox (https://sandbox-api.bachs.io/v1) or live (https://api.bachs.io/v1) base URL.
• BACHS_BASE_URL overrides the base URL entirely when set.

The published config/bachs.php also supports multiple named connections:

Usage

Products

Customers

Billable trait

Add the Billable trait to any Eloquent model (e.g. User) to get billing helpers:

Checkout

Subscriptions

Payments & refunds

Webhooks

Register the webhook route in your routes/web.php:

Set the signing secret in .env:

Listen for typed events in your EventServiceProvider:

Enable local model sync in config/bachs.php:

Blade components

Artisan commands

Low-level transport

BachsClient is the HTTP transport used by the resource layer. It handles authentication, JSON, timeouts, idempotency keys, custom headers, retries with exponential backoff, and typed exceptions:

• Retries: safe methods (GET/HEAD/OPTIONS) and requests carrying an Idempotency-Key retry on 429/5xx and network failures. The delay grows exponentially and a 429's Retry-After is honored.
• Headers: connection-level defaults plus per-request headers. Authorization, Accept, Content-Type, and Idempotency-Key are reserved and cannot be overridden.
• Exceptions: non-2xx responses throw typed exceptions — BachsAuthenticationException (401), BachsValidationException (422), BachsNotFoundException (404), BachsRateLimitException (429), BachsConflictException (409), BachsNetworkException, and the base BachsApiException.

Testing

Changelog

Please see CHANGELOG.md for what changed recently.

Contributing

Please see CONTRIBUTING.md for details.

Security

Please see SECURITY.md for reporting vulnerabilities.

Credits

• Okeke Chimezie Glory
• Bachs.io — the API provider this package wraps.
• Laravel Cashier — whose API design this package is inspired by.

License

The MIT License (MIT). Please see LICENSE for more information.