PHPackages                             graystackit/laravel-mollie-billing - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. graystackit/laravel-mollie-billing

ActiveLibrary[Payment Processing](/categories/payments)

graystackit/laravel-mollie-billing
==================================

Batteries-included Mollie billing for Laravel: VAT/OSS compliance, wallet-based metered billing, coupons, scheduled plan changes, trial flow, admin panel and a Livewire 4 customer portal.

v0.3.3(1w ago)187↓100%MITPHPPHP ^8.3CI passing

Since May 13Pushed 1w agoCompare

[ Source](https://github.com/GraystackIT/laravel-mollie-billing)[ Packagist](https://packagist.org/packages/graystackit/laravel-mollie-billing)[ RSS](/packages/graystackit-laravel-mollie-billing/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (3)Dependencies (13)Versions (16)Used By (0)

graystackit/laravel-mollie-billing
==================================

[](#graystackitlaravel-mollie-billing)

> Batteries-included Mollie billing for Laravel: VAT/OSS compliance, wallet-based metered billing, coupons, scheduled plan changes, trial flow, admin panel and a Livewire 4 customer portal.

[![Latest Version on Packagist](https://camo.githubusercontent.com/b9db1086e072d4b961e34489053d4e6c5187fd6c7596929e2aeca60e36b36ec2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67726179737461636b69742f6c61726176656c2d6d6f6c6c69652d62696c6c696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/graystackit/laravel-mollie-billing)[![PHP Version](https://camo.githubusercontent.com/2e3fb89feb02433ae27123847b4f16a22a10da737abf4a1f834c8d092399e803/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f67726179737461636b69742f6c61726176656c2d6d6f6c6c69652d62696c6c696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/graystackit/laravel-mollie-billing)[![Laravel Version](https://camo.githubusercontent.com/947656787bad2f17fdd46ddf773bba151d4e29a133c447cbf6a878991426ee55/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31322e7825323025374325323031332e782d4646324432303f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c)](https://laravel.com)[![Tests](https://camo.githubusercontent.com/fe591d076f25289f52839f83d07755c017b31b56067ba36e27b0920d3ec20a58/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f47726179737461636b49542f6c61726176656c2d6d6f6c6c69652d62696c6c696e672f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/GraystackIT/laravel-mollie-billing/actions/workflows/tests.yml)[![Total Downloads](https://camo.githubusercontent.com/daa14e3587df54aeac2248402b2502b7ac13a62329b5fc6e3e02ae0614ba80da/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f67726179737461636b69742f6c61726176656c2d6d6f6c6c69652d62696c6c696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/graystackit/laravel-mollie-billing)[![License](https://camo.githubusercontent.com/d8346c96f8aee5fcd56af9ddc789d0f5cdcf55ca86f48b91429a5f7d886bb467/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f67726179737461636b69742f6c61726176656c2d6d6f6c6c69652d62696c6c696e672e7376673f7374796c653d666c61742d737175617265)](LICENSE)

A batteries-included Mollie billing layer for Laravel that wraps `mollie/laravel-mollie` ^4 and adds VAT/OSS compliance, wallet-based metered billing, a coupon engine, scheduled plan changes, an admin panel, and a Livewire 4 customer portal — all keyed off a `Billable` contract that lives on whichever model owns the subscription (typically your `Organization`, not your `User`).

Highlights
----------

[](#highlights)

- Mollie subscriptions, mandates and webhooks (built on Mollie's official Laravel SDK v4 with typed request objects)
- VAT calculation, VIES validation and OSS export (`mpociot/vat-calculator`)
- Country-mismatch reconciliation: three-way reconciliation of user-declared, payment-derived, and IP-derived country at every recurring payment. If the user country matches none of the other signals, the subscription is set to cancel-at-period-end, the billable is notified by email, and the user can self-correct via a dashboard modal (refund + reissue at the corrected VAT rate). B2B billables with a VIES-validated VAT number bypass the check (reverse-charge makes the bank country fiscally irrelevant). Manual admin override available. See [docs/vat-handling.md](docs/vat-handling.md).
- Wallet-based metered billing with included quotas and overage prices (`bavix/laravel-wallet`), with case-insensitive usage-type lookups
- Direct overage charging with retry and `past_due` state
- Five coupon types — `SinglePayment`, `Recurring`, `Credits`, `TrialExtension`, `AccessGrant`
- Access Grants for full-plan or addon-only complimentary access
- Scheduled plan changes, prorata, end-of-period downgrades
- Refunds and credit notes (full, overage units, wallet-only)
- IP-based country pre-fill in the checkout/billing-data dropdown (UX only — never persisted)
- Trial flow with Local-to-Mollie subscription conversion
- Feature gating via `@planFeature` Blade directive and `billing.feature` middleware
- Built-in first-checkout flow with configurable country list, VAT/VIES validation and coupon support
- Livewire 4 SFC customer portal and admin panel, both built on Flux Pro
- Promotion links via signed `/promotion/{token}` URLs
- Localized notifications (English and German out of the box)
- All Livewire SFC views publishable and overridable

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 12 or 13
- A Mollie account with API key
- Livewire 4 (for the customer portal views)
- `livewire/flux-pro` — required for the customer portal, the checkout flow and the admin panel. Not pulled in by this package (commercial license needed); install it separately in your application: `composer require livewire/flux-pro`.

Installation
------------

[](#installation)

```
composer require graystackit/laravel-mollie-billing
```

Publish the config and migrations:

```
php artisan vendor:publish --tag=mollie-billing-config       # mollie-billing.php + mollie-billing-plans.php
php artisan vendor:publish --tag=mollie-billing-migrations
php artisan vendor:publish --tag=mollie-billing-views        # optional: override Blade/Livewire views
php artisan vendor:publish --tag=billing-lang                # optional: override translations
```

Edit `config/mollie-billing.php` and set the billable model:

```
'billable_model' => \App\Models\Organization::class,
'billable_key_type' => 'uuid', // 'uuid' | 'ulid' | 'int'
'user_key_type' => 'int',      // 'uuid' | 'ulid' | 'int' — primary key type of your auth user model
```

> **Important:** `billable_key_type` and `user_key_type` must be set **before running migrations for the first time**. `billable_key_type` controls the column type of every polymorphic foreign key that references your billable — including `bavix/laravel-wallet`'s `wallets.holder_id`, `transactions.payable_id`, and `transfers.{from,to}_id`, which we rewrite from the default `bigint` to `uuid`/`ulid`. `user_key_type` controls columns that reference the auth user (e.g. `billing_country_mismatches.resolved_by_user_id`). Changing them later requires manually altering those columns.

Then run migrations:

```
php artisan migrate
```

### Frontend assets

[](#frontend-assets)

The package ships server-rendered Blade/Livewire views but **no compiled CSS or JS** — it relies on your host app's Vite pipeline. The shipped layouts (`portal`, `checkout`, `admin`) call `@vite(['resources/css/app.css', 'resources/js/app.js'])`, so your app must:

1. Expose those two entry points in `vite.config.js` (the Laravel default).
2. Scan the package's Blade views in your Tailwind build, otherwise utility classes used inside the package will be purged and the portal/checkout will render unstyled. See [Tailwind CSS content source](#tailwind-css-content-source) below for the one-line `@source` (Tailwind v4) or `content` (v3) entry to add.

If you publish the views (`--tag=mollie-billing-views`) and Tailwind already scans `resources/views/**`, the published copies are picked up automatically — but the `@source` line for the vendor path is still needed for any unpublished views.

Verify your configuration before deploying — the package ships a validator that checks both `mollie-billing.php` and `mollie-billing-plans.php` for syntax errors, broken references (unknown `feature_keys`, `allowed_addons`, product `group`, …) and likely misconfigurations:

```
php artisan billing:check-config
```

See the [Commands](#commands) section below for the full list of issues it detects.

Quick start
-----------

[](#quick-start)

Add the `HasBilling` trait and implement the `Billable` contract on your billable model — typically a tenant or organization, not the `User`:

```