Documentation for larsasub v0.38.2. On an older version? Your release notes ship with the package (CHANGELOG.md).

Configuration#

Everything LarsaSub reads lives in config/larsasub.php, which larsasub:install publishes (or php artisan vendor:publish --tag=larsasub-config). This page walks the file block by block, in the order the file declares them: each key with its default, its environment variable and what it does.

Every setting has a working default. The blocks you are most likely to touch first are Billable model, Invoicing and Standalone dashboards. The environment variables on their own are listed in Environment variables.

• Validation and upgrades
• Database connection
• Billable model
• Payment provider
• Currency
• Content locales
  • The model-log language
• Terms acceptance
• Redirect routes
  • A route name
  • An invokable class name
  • connect_callback
• Features
• Data retention
• Scheduling
  • Command frequencies
  • Command settings
  • The execution limit
  • Reconciliation
  • Mandate recovery
  • The overlap mutex
• Policies
  • The admin role
  • Per-model permissions
• Notifications
  • Sales recipients
  • Payment button URLs
  • The subscriber button
  • Tenant admin buttons
  • Attachments
  • Notification toggles
  • Disabled listeners
• Notification channels
• Standalone dashboards
  • Routes and authentication
  • Dashboards and URLs
  • Lists, back button and theme
• License tier
• Mollie Connect
  • Credentials and scopes
  • Tenants
  • Application fees
  • Disconnecting
• Settlements
• Email theme
• Subscription rules
  • before_first_charge — cost lines on the first charge
  • free_plan_mandate — what a free plan does about the mandate
• Dunning
• Invoicing
  • VAT and prices
  • Seller and numbering
  • VAT number validation
• Reference codes
• Logging
• Table prefix
• Webhooks
• Ngrok

Validation and upgrades#

LarsaSub checks its own configuration on every boot (Support\ConfigValidator) and reports what it finds at two severities. You rarely need to think about this until a value is wrong — but knowing the two severities tells you where to look when it is.

php artisan larsasub:doctor prints the same fatals and warnings on demand, plus the checks boot cannot make: whether configured route names exist, whether the schema has every column, whether a published view predates a key you set, and findings that need the database. It exits non-zero on an error; --strict also fails on warnings, and --live adds one read-only call to the provider. The sections below say which keys these checks cover.

A published config does not pick up new nested keys. Laravel merges your published config/larsasub.php with the package's own at the top level only. A block you published before a key was added keeps your copy, and the new key reads as null — which for some keys switches a feature off (a missing retention.notification_deliveries_days disables pruning). larsasub:doctor lists every key the shipped file has and yours lacks. Re-publish with php artisan vendor:publish --tag=larsasub-config --force, or copy the keys in by hand.

Database connection#

Every LarsaSub table lives on one connection. Change it when billing state should sit apart from your application's own data.

'database' => [
    'connection' => env('LARSASUB_DB_CONNECTION', null),
],

null is right for a single-database app. Multi-tenant apps typically point it at a landlord connection, so billing state survives independently of the per-tenant databases:

'connection' => env('LARSASUB_DB_CONNECTION', 'landlord'),

The package also registers a larsasub channel on peters-development/laravel-model-logger with this connection, so model-log rows land beside the records they describe — unless you declare that channel yourself in the model logger's config.

Testing. If your test suite points this at a differently named connection that shares the default's PDO, RefreshDatabase's wrapping transaction becomes invisible to the package and every money-path test dies with "cannot start a transaction within a transaction". See Testing.

Billable model#

This block decides which of your models holds subscriptions and gets charged, and how the package finds it from the signed-in user.

'billable' => [
    'model' => \App\Models\User::class,
    'resolution_mode' => env('LARSASUB_BILLABLE_RESOLUTION_MODE', 'auto'),
    'owner_resolver' => null,
    'relation' => null,
    'platform_model' => null,
],

model must implement Contracts\BillableModel (a boot failure otherwise) and use Traits\IsBillableModel. With the Mollie provider it also needs IsMollieBillableModel; larsasub:doctor reports the methods that are missing. See Billable models.

Direct billing (relation => null) makes the authenticated model itself the billable. Indirect billing (relation => 'team') names a relation on the user that returns the billable, so several users share one subscription.

Explicit mode is for apps where one user owns many billables — a multi-tenant SaaS where the "current" tenant comes from the subdomain, not from a user attribute. In that mode BillableResolver::resolve() throws unless owner_resolver is configured, and you pass the owner explicitly everywhere else. Without a resolver, ownership policies and the bundled dashboards fail closed — they deny, never a 500. See Billable models.

owner_resolver is called as __invoke(?Authenticatable $user): ?Model and must return null (no current owner, e.g. on landlord routes) or a model implementing BillableModel. It runs in the request, so reading request state is what it is for. It is ignored outside explicit mode.

platform_model sets up dual billing alongside Connect: the platform bills this model through its own Mollie key, while the primary model is billed through the tenant's Connect account. Both classes must implement BillableModel.

Boot fails on a model or platform_model that is not an existing class implementing BillableModel, a resolution_mode other than auto or explicit, and an owner_resolver that is not an existing invokable class.

Payment provider#

Mollie is the only provider the package ships. These two keys exist so a host can replace or extend it without patching the package.

'provider' => env('LARSASUB_PROVIDER', 'mollie'),

'providers' => [
    'mollie' => \PetersDevelopment\LarsaSub\PaymentProviders\Mollie\MollieService::class,
],

provider selects the active provider; providers is the registry it is looked up in. A host can register its own implementation here (it must extend PaymentProviders\Contracts\PaymentProviderService) or point an existing name at a subclass. Services resolve through the container, so a container binding can override behaviour without touching this map.

The package registers the active provider's own routes — its webhooks and payment initiation — through this registry, so a custom provider gets its webhook routes, not Mollie's. Boot fails when provider is not a key of providers, or a class in it does not exist.

Currency#

LarsaSub bills in euros. default is the currency the package creates money in itself; allowed is an allow-list for the two places where a caller names one.

'currency' => [
    'default' => env('LARSASUB_CURRENCY_DEFAULT', 'EUR'),
    'allowed' => array_filter(array_map('trim', explode(',', env('LARSASUB_CURRENCY_ALLOWED', 'EUR')))),
],

allowed is enforced, not documentation. The two entry points where a caller supplies a currency reject anything outside it, compared case-insensitively: SinglePaymentService::createSinglePayment() with a SinglePaymentException, and RecurringChargeService::createStandaloneCharge() with a RecurringChargeException. Boot fails when default is not in allowed.

EUR is the only supported default. Plans, subscriptions, the €0,01 mandate verification and credit all use that one currency, and the package converts nothing. Another default is not supported yet: SEPA Direct Debit, iDEAL and Bancontact take euros only, the VAT rules zero-rate every customer outside the EU (a seller in the UK or Switzerland would charge its own domestic customers no VAT), and the display formats money the euro way.

A customer outside the euro area pays in euros, by card or PayPal; their card issuer or PayPal converts it to their own currency.

A second code in allowed lets those two entry points collect in it, at the amount you pass: Mollie collects in that currency, and only a method that accepts it (a card, PayPal) can complete the payment. Its invoice and credit note state that currency. Such a charge is never paid from credit — the credit account is in default, and credit is applied only within one currency (Credit) — and neither is a chargeback follow-up of it. A plan's price_currency is not checked against allowed: keep it at default.

Content locales#

This block turns on per-language plan content and fixes the one language the package writes its model logs in.

'locales' => [
    'supported' => ConfigHelpers::parseContentLocales(env('LARSASUB_LOCALES', '')),
    'default' => env('LARSASUB_LOCALE_DEFAULT'),
    'fallback' => env('LARSASUB_LOCALE_FALLBACK'),
    'log' => env('LARSASUB_LOG_LOCALE'),
],

null for supported is single-language mode — nothing changes anywhere. Setting it turns plan content into per-locale translations, resolved to the viewer's locale when read; frozen text (charge, invoice and payment descriptions) is written in the billable's locale. Read Multilingual plan content before enabling it; in particular, never narrow supported while translated content exists. Existing single-language content is migrated with php artisan larsasub:promote-translations {locale}.

Setting default explicitly is recommended. It is deliberately not app.locale, which locale middleware changes per request.

The model-log language#

log is the one language every model-log line is written in — the History of a subscription, charge or mandate in Nova or Filament — whoever acted and whatever locale the request or a mailer had set at that moment. null means app.locale as it stands when the package boots, not at the time of writing: webhooks, queue workers and scheduled commands write most of these lines, and middleware and mailers change the locale.

The package's service provider boots before your AppServiceProvider. An App::setLocale() in your provider's boot() — or in middleware — therefore does not change the log language; only config/app.php's locale does. If the History should be in another language, set it here: LARSASUB_LOG_LOCALE, or larsasub.locales.log in your published config. A config published before the key existed has no log key, so the env variable is not read until you add it; larsasub:doctor lists locales.log as missing.

The package ships en and nl. For another language the lines must actually translate: a lang/vendor/larsasub/<locale>/ override counts only when it translates the log groups. Otherwise the boot warns and every line is written in app.fallback_locale — or, when that cannot render them either, stored as its raw key (still re-renderable from the row's meta). larsasub:doctor prints the log language and whether it renders. See HasModelLogs for re-rendering a line in another language.

Terms acceptance#

Turn this on when the bundled subscribe flow should make subscribers accept your terms and keep evidence of it.

'terms' => [
    'provider' => env('LARSASUB_TERMS_PROVIDER'),
    'documents' => [],
    'withdrawal_consent' => env('LARSASUB_TERMS_WITHDRAWAL_CONSENT', false),
],

null (default) disables the feature entirely; hosts that form contracts through their own flows keep enforcing and recording consent themselves. Naming a TermsProvider makes the bundled subscribe flow require a terms checkbox and record the acceptance. Boot fails on a provider class that does not exist or does not implement the contract.

Append new versions to documents; never edit an entry that already shipped. withdrawal_consent is read only while a provider is configured: it adds a second checkbox, recorded as a separate acceptance linked to the subscription. See Terms acceptance and Withdrawal consent.

Redirect routes#

These keys decide where the customer's browser lands after returning from the payment provider.

'redirect' => [
    'first_payment' => 'larsasub.my-subscription.view',
    'manual_charge_payment' => 'larsasub.my-subscription.view',
    'mandate_setup' => 'larsasub.my-payment-methods.view',
    'connect_callback' => 'larsasub.tenant-connect.view',
    'single_payment' => 'larsasub.my-payments.view',
],

Each key takes one of two shapes: a route name, or an invokable class name.

A route name#

The default. The package passes the context as route parameters, so they become path segments where your route declares them and query parameters otherwise:

An invokable class name#

A value shaped like a namespaced PHP class name (App\Billing\Foo: identifier segments separated by backslashes, a leading one allowed). Nothing else is: larsasub.my-subscription.view is a route name, and so is anything with a character a class name cannot hold, backslash or not. Laravel accepts any string as a route name, including one of that shape, so the rule is "if it could be a class name, it is read as one" — rename a route named that way.

Use it for a host with more than one kind of checkout (an office UI next to an onboarding wizard), where one global route name would have to multiplex on query parameters:

'redirect' => [
    'first_payment' => \App\Billing\FirstPaymentReturnUrl::class,
],

namespace App\Billing;

use PetersDevelopment\LarsaSub\Models\RecurringCharge;

class FirstPaymentReturnUrl
{
    public function __invoke(?RecurringCharge $charge, ?string $origin = null): ?string
    {
        // Return an absolute http(s) URL, or null to use the package fallback.
        if ($charge === null) {
            return null;
        }

        // Routing on the charge is safe; RENDERING it is not — see the note
        // below. `charge` here is the same id the incoming URL already held.
        return $this->startedInOnboarding($charge)
            ? route('onboarding.done', ['charge' => $charge->id])
            : route('office.billing.return', ['charge' => $charge->id]);
    }
}

The page you send them to is where ownership gets checked, the same way any other page of yours does it. If instead you want to decide the destination from something only the owner may know — or put anything from the charge in the URL that was not already in it — verify ownership first and return null when you cannot:

$user = auth()->user();   // null on the return endpoints more often than not

if ($user === null || ! $user->owns($charge)) {
    return null;          // the package falls back to its own chain
}

The failure contract is deliberate: this runs on the page that confirms a payment, so a throw, a relative URL, an empty string or a non-string answer is logged and falls back — never a 500. The chain is invokable → your route name (if registered) → the bundled default (if registered) → config('app.url').

A class name that does not exist, or has no __invoke(), fails at boot. A route name that does not exist is reported by php artisan larsasub:doctor (routes are not loaded yet at boot, so that one cannot be caught there).

Security — what "verify ownership" means here. Your invokable runs in two places, and it cannot tell them apart. One is the subscribe request your own UI made, where the customer is logged in and the package just created the charge it hands you. The other is the four return endpoints, which carry no auth middleware by design — their URLs are embedded in the payment at the provider and a customer coming back from their bank may have no session — and which bind the model from an id in the URL, so anyone may name any charge.

No argument tells the two apart, deliberately. A provenance flag would only be useful to license trusting the model on the first path, and that is a property the package cannot promise for call sites it has not added yet. auth()->user() is not that flag either: it is usually null on the return endpoints, and when it is not, the session user is still no evidence that this charge is theirs.

So the rule is uniform, and it is narrower than "never touch it": route on the model, do not render it. Picking a destination from an unverified charge leaks nothing, and echoing back an id that was already in the incoming URL leaks nothing either. What does leak is amounts, descriptions, billable or provider identifiers — anything the caller did not already have. Need any of that? Then check ownership explicitly (and return null when you cannot), or put it on the destination page, behind your own auth.

connect_callback#

connect_callback is resolved only when the tenant owner starts the Mollie Connect flow; the later steps have no tenant yet and keep the plain route name. Its URL must live on the origin the flow started from — the package computes that origin as a security control (an attacker-controlled Host header would otherwise become an open redirect) and passes it as the second argument, so do not derive it yourself. You may return a path, which the package prefixes with that origin. Do not return a fragment: the package appends connect_success=1 / connect_error=... as a query parameter and a fragment would swallow it.

Features#

Feature defaults give every plan a baseline of free-form values your application checks ($billable->hasFeature('max_users')). They ship empty.

'features' => [
    'default' => [],   // e.g. ['max_users' => 5]
    'tenant'  => [],   // e.g. ['max_lessons' => 10]
    'labels'  => [],   // e.g. ['max_users' => 'Team members']
],

Feature keys and values are yours. Resolution order is config defaults → Subscription.features → BillableSubscription.feature_overrides; read them with hasFeature(), featureValue() and featureList() (see Subscriptions).

labels maps keys to display names — plain strings, or translation keys resolved through __(). An unlabelled key shows as the raw key.

Data retention#

How long the package keeps its own operational records. Three daily prune commands read these keys.

'retention' => [
    'model_logs_days' => env('LARSASUB_MODEL_LOGS_RETENTION_DAYS', 730),
    'notification_deliveries_days' => env('LARSASUB_NOTIFICATION_DELIVERIES_RETENTION_DAYS', 365),
    'dunning_days' => env('LARSASUB_DUNNING_RETENTION_DAYS'),
],

Any value that is not a positive number — null, 0, empty — disables pruning for that table. Model-log entries and delivery records older than the number of days are deleted in bounded chunks.

The ~2-year model-log default comfortably outlives the SEPA 13-month chargeback window a disputed direct debit needs the trail for. Notification deliveries are kept shorter on purpose: deduplicating a retried job needs minutes of history, and the longer window only serves the question "was that payment reminder actually sent?" — which surfaces within the year. Those rows carry no fiscal trail; model logs do.

dunning_days is null by default: a resolved reminder series documents how a debt was pursued. Only resolved series (paid or closed) are ever pruned, and never one whose charge is still an unpaid debt — deleting it would let the series start over (Reminder series).

Scheduling#

LarsaSub's recurring work — planning and collecting charges, ending and renewing subscriptions, reminders, pruning — runs as scheduled artisan commands. This block registers them with Laravel's scheduler and tunes what they do.

'scheduling' => [
    'enabled' => env('LARSASUB_SCHEDULING_ENABLED', true),
    'auto_register' => env('LARSASUB_SCHEDULING_AUTO_REGISTER', true),
    'timezone' => env('LARSASUB_SCHEDULING_TIMEZONE', null),
    // … one *_frequency key per command, and the settings below …
],

With enabled off, recurring billing stops: no charge is planned or collected, and larsasub:doctor says so. The full per-command treatment lives in Scheduled commands.

Command frequencies#

One key per scheduled command. Only the names of these Laravel scheduler methods are understood: everyMinute, everyTwoMinutes, everyThreeMinutes, everyFourMinutes, everyFiveMinutes, everyTenMinutes, everyFifteenMinutes, everyThirtyMinutes, hourly, everyTwoHours, everyThreeHours, everyFourHours, everySixHours, daily, twiceDaily, weekly, monthly.

A misspelled frequency is silent. Anything else registers as that command's own default — the value in the table below, not daily — without a warning. A mistyped cleanup_unused_billable_subscriptions_frequency runs twiceDaily, a mistyped validate_mandates_frequency runs weekly.

plan_charges_frequency must run every day, at or before the first execute-charges run. A subscription charge is planned on its collection day, and plan-charges is registered before execute-charges, so on the shipped daily both run at midnight and the charge planned then is collected in the same tick. weekly or monthly collect up to six days or a month late; twiceDaily (01:00 and 13:00) against a daily execute run (00:00) collects every charge a day late. Boot warns about those combinations and larsasub:doctor lists them — both only while auto_register is on, because otherwise your own scheduler decides and the package cannot read it. renew_billable_subscriptions_frequency must run at or before the planner's first run each day (daily and anything more frequent from midnight do). A twiceDaily renewal (01:00 and 13:00) is late beside a daily planner, which plans the renewed term the next day, and beside a daily execute-charges, which collects it the next day; weekly or monthly wait for their next run. Boot warns about those as well, as does larsasub:doctor, again only while auto_register is on.

execute_charges_frequency is also half of a safety net — see Reconciliation.

Command settings#

The execution limit#

The limit is one budget across both collection loops (subscription and standalone charges), counting every charge the run takes up — including the ones it skips. Leftovers keep their past planned_on and are collected by the next run, so lowering it spreads the work out and never drops a charge. null, empty or any non-positive value means no limit, which is the default.

Do not set a cap without sizing it. Capacity is limit × runs per day, and larsasub:end-billable-subscriptions is not limited: if execution lags past a subscription's end_date (a fixed term without renewal, or a cancellation), that subscription is deactivated first and its last charge is then parked with needs_attention instead of collected — and a charge on an inactive subscription is not payable by the customer either. A too-low limit is a money bug, not a performance knob. Full explanation: Limiting one execution run.

Each pass before the collection loops takes its own slice of this limit: mandate recovery, the reconciliation of unresolved charges and of unresolved single payments, the look for reversed chargebacks, and the reconciliation of stranded chargeback follow-ups. A limit of 50 is therefore up to five budgets of 50 records plus 50 collections, not 50 calls in total. And a record is not a call: a reversal look costs two provider requests, and a mandate repair at least two and usually more, because adopting a mandate walks the customer's mandate list. See SCHEDULING.md.

Reconciliation#

A charge can end up claimed but unresolved when a run is killed between claiming it and storing the provider's answer. larsasub:execute-charges asks Mollie what happened to such claims; these keys tune that.

reconcile_unresolved_after_minutes — values of 60 or more are clamped to 59: reconciliation releases a charge it cannot find at the provider and the executor retries it, which is only safe while Mollie still holds the idempotency key from the first attempt — and it holds those for one hour. The clamp bounds this threshold only. The age a claim really reaches is this value plus the execute_charges_frequency interval, so keeping the safety net means scheduling execute-charges often enough for the sum to stay under 60. The shipped daily does not (30 + 1440), and neither does hourly (90); everyThirtyMinutes lands exactly on 60, which is not under it.

The package computes that sum for you. larsasub:doctor prints it as a Reconciliation window line — threshold plus interval, with the threshold as it will be applied (clamped) rather than as configured — and ConfigValidator logs a warning while it is 60 or more. On the shipped defaults that warning fires (30 + daily = 1470): either schedule execute-charges at everyFifteenMinutes or finer, or take it as read that the retry-dedup net is not there. That is a defensible choice — the net only matters for a run that dies between claiming a charge and storing the answer — as long as it is a choice. A frequency the scheduler does not recognise is judged as the default it is registered as. Both go quiet when scheduling.auto_register is off, because then your own scheduler decides the interval and the package cannot read it — that case is yours to check.

reconcile_lookup_ceiling — a history of exactly that many payments is still walked in full; one payment more stops the walk and parks the charge with needs_attention rather than releasing it: "we stopped looking" is not "there is nothing there", and releasing would charge twice.

reconcile_park_after_hours is the grace period a record gets before reconciliation gives up on it. It is measured from the claim itself (charged_at on a charge; updated_at on a single payment and on a chargeback follow-up, whose charged_at is empty on a first attempt and the first attempt's on a retry), not from the first failure. While the claim is younger than this, a reconciliation that cannot resolve it logs and defers, and the record stays eligible for the next run. Older than this, it is parked with needs_attention in front of an operator.

Parking on the first failure is what this avoids. Parking removes a record from every future run, so a transient hiccup — Mollie briefly unreachable, a tenant database restarting — would otherwise orphan the claim permanently: its webhook cannot match a row that has no provider id, and the reconciler would never come back for it.

Mandate recovery#

The shape: the payment succeeded, the mandate registration behind it threw, the charge was flagged — money in, subscription active, nothing to collect the next period with. Each run retries the registration, and a mandate recovered that way is used by the same run. Past the window the state is left in front of an operator rather than retried forever.

It is not an off switch, and the values that look like one are the trap. null and '' mean the default of 30; anything else is read as an integer and raised to at least 1 — so 0, false and any non-numeric value leave the pass running, creating mandates at the provider and mailing the subscriber, with a window of one day. Close enough to off to be mistaken for it, which is why ConfigValidator warns about those values instead of honouring them. Only a positive number of days belongs here. Nor is there a way to keep collection without the pass: it runs first in every larsasub:execute-charges run, and RecurringChargeService::scheduleExecute() is the only public entry to the collection loops. Keep the window small instead.

The retry can create a mandate at the provider, not only adopt one that is already there. On the EU and mandate-setup flows only the local registration failed, so it is an adoption; on the NL flow LarsaSub itself makes the mandate from the IBAN of the first iDEAL payment, so a registration that never completed left nothing to adopt and creating one is the only repair available. The subscriber gets the ordinary "payment method added" mail for it.

That is why recovery keys on that failure's own marker and on nothing else: a charge a customer repaired by hand with iDEAL fits every symptom, and repairing it would create a SEPA direct-debit mandate they never authorized. A subscription that is already deactivated is skipped, and a payment method the customer removed is never brought back either. Full explanation: A paid first payment without a mandate.

The overlap mutex#

Every auto-registered command runs withoutOverlapping(). The expiry is a stale-lock cleanup, not a guarantee — a run that outlives it loses its slot and the next tick starts alongside it. That costs contention and duplicate work, not double billing (the execution claim catches that); raise it when runs legitimately take longer than an hour. The mutex lives in the default cache store, so on multiple app servers that store must be shared (redis, memcached, database) or it protects nothing between servers. See Overlap protection.

Policies#

Authorization for LarsaSub's models. Policies are always enforced in user context (controllers, API routes, admin panels) and never in system context (scheduled commands, service methods).

'policies' => [
    'admin_role' => ConfigHelpers::parseAdminRole(env('LARSASUB_ADMIN_ROLE', '')),
    'models' => [ /* per model, below */ ],
],

Policies decide the same way on every route, admin panel or not.

For behaviour a config map cannot express, bind your own policy class for a LarsaSub model with Gate::policy().

The admin role#

admin_role accepts four forms:

The invokable runs in the request, so reading request state there is fine — unlike the notifications.*_url hooks, which run in the queue worker.

With no admin role configured, nobody is an admin. That is the default. In simple mode the management dashboards (plans, subscribers, charges, invoices) authorize through admin_role, so nobody passes and a denied request logs an explanatory line. Boot warns while it is empty.

Per-model permissions#

Each model key takes admin_only, ownership_required and an actions map. An action resolves in this order:

1. An entry in actions wins: true, false, 'admin', 'owner_or_admin', 'owner' or 'authenticated'. Any other value denies, with a log line.
2. Otherwise admin_only => true makes it 'admin'.
3. Otherwise ownership_required => true makes viewAny and view 'owner_or_admin'.
4. Otherwise the action is allowed.

A model key removed from a published config denies every action.

'billable_subscription' => [
    'ownership_required' => true,
    'actions' => [
        'viewAny' => 'owner_or_admin',
        'view' => 'owner_or_admin',
        'create' => false,
        'update' => 'admin',
        'subscribe' => true,
        'cancel' => 'owner_or_admin',
        'terminate' => 'owner_or_admin',
        'retryPayment' => 'owner_or_admin',
        'changeSubscription' => 'owner_or_admin',
        'changePaymentMethod' => 'owner_or_admin',
    ],
],

The shipped defaults, per model key (delete, forceDelete, restore and replicate are false wherever an actions map is shipped, except where listed):

One action has its own environment variable: LARSASUB_SELF_SERVICE_CREDITS is the value of policies.models.billable_credit.actions.purchase — whether subscribers may buy credit for themselves from the credit dashboard. Everything else under policies.models is config-file only.

Notifications#

Who receives the package's mails, where their buttons point, what they carry, and which ones are sent at all.

'notifications' => [
    'sales' => ConfigHelpers::parseNotificationRecipients(env('LARSASUB_NOTIFICATIONS_SALES', '')),
    'payment_url' => env('LARSASUB_NOTIFICATIONS_PAYMENT_URL'),
    'first_payment_url' => env('LARSASUB_NOTIFICATIONS_FIRST_PAYMENT_URL'),
    'user_app_url' => env('LARSASUB_NOTIFICATIONS_USER_APP_URL'),
    'tenant_admin_url' => env('LARSASUB_NOTIFICATIONS_TENANT_ADMIN_URL'),
    'tenant_model_url' => env('LARSASUB_NOTIFICATIONS_TENANT_MODEL_URL'),
    'attachments' => env('LARSASUB_NOTIFICATIONS_ATTACHMENTS', false),
    'user' => [ /* per-notification toggles */ ],
    'company' => [ /* per-notification toggles */ ],
    'disabled_listeners' => [],
],

Every URL hook and the attachments hook run in the queue worker, not in a request. All context must come from the argument the invokable receives. It must not read auth(), session(), request() or a container-bound "current tenant" singleton. billable.owner_resolver documents exactly the opposite (request-scoped) pattern on purpose; copying it here yields an empty or wrong tenant. Anything an invokable throws is caught and logged, and the mail falls back — a button is not a money path. Name a class, never a closure: a closure does not survive config:cache.

A value that reads as a class name but is not an existing invokable class is a boot failure for every URL key and for attachments.

Sales recipients#

notifications.sales accepts a role name (requires spatie/laravel-permission), a comma-separated email list, a single email, or an empty value to disable.

An address is matched case-insensitively to a user of auth.providers.users.model. One without a user account is still mailed, on an on-demand mail route — which only the mail channel can take (see Notification channels).

In Connect mode a company mail about a tenant's subscriber goes to that tenant's admins instead; the platform's sales recipients get it as well only with connect.notifications.also_notify_platform on, or when no tenant recipient could be reached.

Leaving sales empty discards every company notification that has no tenant to go to — silently, since there is nobody to send them to. Boot warns while it is empty.

Payment button URLs#

payment_url decides where the pay button of three mails points: the payment-failed mail; the chargeback mail, where the charge it receives is the chargeback's follow-up charge — the debt ($charge->isChargebackFollowUp() is true, usually charged_at NULL) — never the charged-back original, which is paid; and the dunning reminder, whose charge is the debt the series chases (a failed charge, possibly a standalone one without a subscription, or a follow-up).

first_payment_url is the retry button of the first-payment-failed mail. It is a separate key on purpose: retrying a failed first payment is a subscription action (retry, or terminate the never-activated subscription), not a payment-page action. Point it at the page where your app offers that retry.

Both take three forms:

The invokable is the form for multi-tenant hosts whose pay page lives on a per-tenant host, where one static URL cannot serve every subscriber.

Leaving both empty only works while their dashboard is registered. With the payments dashboard off, an empty payment_url leaves the payment-failed, chargeback and reminder mails without a pay button — only the generic app button remains — and with the subscription dashboard off, an empty first_payment_url leaves the first-payment-failed mail with no action button at all. Boot warns for exactly that combination, and also when explicit billable mode, the reminder series and an empty payment_url meet: the payments dashboard shows the signed-in user's billable, not necessarily the one the mail is about.

The subscriber button#

user_app_url decides where the "go to :appName" button under every subscriber mail points — activation, cancellation, change, the upcoming-collection notice, credit, the payment receipt. The two keys above put an action button in one specific mail; this one sets the default destination of all the rest, and an action button always keeps its own URL.

Set it whenever a subscriber's environment lives somewhere other than config('app.url'). Under Connect a user mail already carries the tenant's name and colours, and this is what makes its button follow the tenant too. But nothing about the key is gated on Connect: a host with per-tenant hostnames and no Connect — the platform billing its tenants, each on its own domain — is the same case, and usually the one where app.url is the marketing site. Only a genuinely single-hostname app has nothing to set here.

The billable, not the tenant: it is what every user mail has, and the tenant follows from it ($billable->resolveTenant()) while the reverse does not. A mail without a billable never calls the invokable.

Two things it deliberately does not touch. Company mails: those go to the tenant's admins and the platform's sales recipients at once, and for the second config('app.url') is the correct answer — tenant_admin_url is where the first half is answered. And the footer line: "sent by <platform>" names the platform (config('app.name'), separate from the tenant-aware app name above), so it is an attribution rather than a way back.

Boot warns about a value that is neither an absolute http(s) URL nor a class name (a template such as https://{tenant}.example is ignored: nothing is substituted), and about a value that is not a string at all — a closure, most likely.

Published emails/layout.blade.php? The button there reads $appUrl, and this key arrives as a new $userAppUrl variable — so setting it does nothing until you port that one line. Nothing errors and nothing logs; larsasub:doctor is what catches it, and UPGRADE.md holds the diff.

Tenant admin buttons#

Both keys are Connect-only and concern company mails read by a tenant's own admins. What neither ever falls back to is the platform's own URL — the one address a tenant must not be sent — so the mail carries one fewer button instead.

tenant_admin_url is where the "go to admin" button points for the tenant's admins. The platform's admin URL comes from the admin-panel package; a tenant's cannot. The chain is: this key, then a resolver registered for the tenant audience, then the first registered bundled tenant dashboard of subscribers, charges, subscriptions and connect (in that order), then no admin button at all. That dashboard fallback resolves with route() against app.url, so set this key even when you run the bundled dashboards if your tenants have their own domains. See The admin button knows who is reading.

tenant_model_url is the same idea one level down: where a tenant views one record, for the "view payment" / "view subscription" deep link. Unset is a supported state: the mail keeps its single admin button. See The deep link to one record.

Returning null falls through to a resolver registered for the tenant audience, and then to the next step of the chain. Boot warns about a value that is neither an absolute URL nor a class name, about a non-string value, and — for tenant_admin_url — when Connect is on, the key is empty and those four tenant dashboards are all off, which leaves tenant admins without any admin button.

Attachments#

notifications.attachments decides whether the package's mails carry a file. Most of these mails are signals, so nothing is attached by default.

The invokable runs in the queue worker, inside toMail(); anything thrown costs the attachment rather than the mail. With 'invoice', turning on notifications.user.payment_paid is what gives a recurring mail to hang the invoice on — otherwise only the activation mail carries one. See Attachments.

Notification toggles#

notifications.user and notifications.company switch individual mails on and off. Turning a user key off is the handover between "the package mails your customer" and "you do": with it off nothing is sent, so nobody is mailed unless you mail them. See Notifications for which event drives each one.

All default to on, with eight exceptions: the three company credit notices; user.payment_paid and company.recurring_charge_paid — the receipt for a collection that simply worked, which on a continuous subscription is a mail every billing period (see Notifications); user.subscription_started and company.subscription_started, the upcoming→active notice only hosts with deferred starts ever see (see Notifications); and company.dunning_reminder, a copy of every reminder step.

The user toggles are config-file only:

The company toggles each have an environment variable:

A toggle that is not a boolean is read the way PHP's boolean filter reads it: true, 1, yes and on are on, anything else — an empty value included — is off. Boot warns about each non-boolean toggle and says how it reads. Boot also warns when chargeback follow-ups are on while company.payment_needs_attention or user.chargeback is off, and when the reminder series reminds customers while user.dunning_reminder is off.

Disabled listeners#

disabled_listeners takes fully qualified listener class names, for replacing one default listener with your own without turning its toggle off for everyone — notification listeners only (the Send*Listener classes):

'disabled_listeners' => [
    \PetersDevelopment\LarsaSub\Listeners\BillableSubscription\SendSubscriptionActivatedToUserListener::class,
],

Any other class there does nothing, and the boot check and larsasub:doctor warn about it. The package's automatic settlement of a double-paid chargeback follow-up is switched off with dunning.double_paid = 'signal', not here.

Notification channels#

Which channels the package's notifications are sent through, globally and per notification class.

'notification_channels' => [
    'default' => ConfigHelpers::parseNotificationChannels(env('LARSASUB_NOTIFICATION_CHANNELS', 'mail')),
    'overrides' => [
        // \PetersDevelopment\LarsaSub\Notifications\RecurringCharge\Company\RecurringChargeFailedNotification::class => ['mail', 'database'],
    ],
],

Only mail and database (which needs Laravel's notifications table) reach a package notification. A notification goes out only on the channels it has a method for: every package notification has toMail(), and the company notifications — all but the credit-expiring and credit-expired ones — also toDatabase(). Any other channel in the list (slack, broadcast, a custom class) is skipped for that notification, with a log warning.

The database channel is safe with per-tenant databases: Laravel writes that row through the notifiable's own relation. A channel that persists through its own model is not — see Multi-database tenancy.

Boot warns when a channel list holds only model-bound channels (database, broadcast) while your owner model has no Notifiable and is mailed at its billable_email address: such an owner cannot receive those mails at all.

Company mail has the same limit. An address in notifications.sales without a user account gets company mail on an on-demand mail route, so a channel list a company notification reads — the default, or an override for a company class — without mail drops every one of those mails. larsasub:doctor names the addresses and the lists; boot cannot, because telling an address from a user account takes a query.

Standalone dashboards#

The bundled Vue dashboards: how their routes are registered and protected, which ones exist, and how they look. Full treatment in Standalone dashboards.

'standalone' => [
    'middleware' => ConfigHelpers::parseMiddleware(env('LARSASUB_STANDALONE_MIDDLEWARE'), ['web', 'auth', 'verified']),
    'guard' => env('LARSASUB_STANDALONE_GUARD'),
    'domain' => env('LARSASUB_STANDALONE_DOMAIN'),
    'page_size' => env('LARSASUB_STANDALONE_PAGE_SIZE', 50),
    'list_limit' => env('LARSASUB_STANDALONE_LIST_LIMIT', 500),
    'dashboards' => [ /* twelve switches, all true */ ],
    'url' => [ /* one prefix per dashboard */ ],
    'show_back' => env('LARSASUB_STANDALONE_SHOW_BACK', true),
    'back' => env('LARSASUB_STANDALONE_BACK_URL', '/'),
    'theme_view' => env('LARSASUB_STANDALONE_THEME_VIEW'),
],

Routes and authentication#

standalone.middleware is the COMPLETE stack. What you put here is what the routes get; the package wraps nothing around it, the same way Nova, Horizon and Telescope treat their own middleware key. Keep web unless your guard is stateless — it carries the session and CSRF verification, and without it the dashboards still render while every action (cancel, change, pay, save profile) answers 419. Replace the list for your own auth middleware, to drop email verification, or to add a tenant-resolution step. An empty value keeps the default rather than publishing billing pages openly.

standalone.guard names the guard the package reads the current user from. When you point it at a non-default guard, authenticate against that guard in the middleware too (auth:billing) — otherwise the route authenticates one user and the package reads another, which renders fine and denies every action. ConfigValidator warns at boot and larsasub:doctor reports it.

standalone.domain constrains the dashboards to one host. It also decides the origin a Mollie Connect flow returns to: without it, that origin comes from the request's Host header, which is only safe behind Laravel's TrustHosts middleware (the package logs a warning when neither is in place).

The same middleware and domain also apply to the Mollie Connect authorize, complete, disconnect and cancel-disconnect routes. Three groups of routes are deliberately not covered by these keys: the provider webhooks (unauthenticated by design — the provider calls them), the Connect OAuth callback (registered at Mollie and built from app.url; it only hands over to the protected complete route, which checks the user), and the return endpoints after a payment (plain web, because their URLs are embedded in payments at the provider and a returning customer may have no session).

Dashboards and URLs#

Each dashboard has an on/off switch under standalone.dashboards and a URL prefix under standalone.url. All twelve default to on; switching one off unregisters its routes entirely.

Two switches are not enough on their own:

• invoices and tenant_invoices are only registered while invoicing.enabled is on.
• tenant_connect and tenant_fees are only registered in Connect mode.

The tenant_* management dashboards are mode-aware: under Connect they are the tenant owner's view of their own tenant; in simple mode they are operator management over the global plans, authorized through policies.admin_role. Turning off the payments or subscription dashboard affects the mail buttons that fall back to them — see Payment button URLs.

Lists, back button and theme#

Put your theme or stylesheet markup in the theme_view view — @vite([...]), <link> tags, whatever your asset pipeline uses. A stylesheet that redefines the theme tokens (--background, --primary, …) on :root / .dark re-themes the dashboards. A view name that does not exist is skipped. See Theming.

larsasub:doctor warns when a dashboard is on and the published assets are missing (php artisan vendor:publish --tag=larsasub-assets).

License tier#

The licence you hold, declared by you. It is the only place your licence is recorded.

'license' => [
    'tier' => env('LARSASUB_LICENSE_TIER', 'single'),
],

This is a declaration you make, not a check the package runs: nothing here is verified, signed or sent anywhere, and the package never contacts larsasub.eu. php artisan larsasub:license reads it back. Case and surrounding spaces are ignored, and an empty value reads as single.

Enabling Connect on a tier other than platform makes the package refuse to boot rather than quietly bill on a licence that does not cover it. Only the recovery commands listed under Validation and upgrades still run, so you can correct the config. See larsasub.eu/pricing.

Mollie Connect#

Connect lets each tenant connect its own Mollie account through OAuth, so their subscribers pay into it. With enabled off (the default) the package is in simple mode: one global Mollie API key. See Mollie Connect for the whole feature.

'connect' => [
    'enabled' => env('LARSASUB_CONNECT_ENABLED', false),
    'tenant_relation' => env('LARSASUB_CONNECT_TENANT_RELATION', null),
    'tenant_context' => null,
    'client_id' => env('MOLLIE_CONNECT_CLIENT_ID'),
    'client_secret' => env('MOLLIE_CONNECT_CLIENT_SECRET'),
    'scopes' => ['payments.read', 'payments.write', /* … */, 'onboarding.read', 'settlements.read'],
    'platform_organization_id' => env('MOLLIE_ORGANIZATION_ID'),
    'fee' => [
        'enabled' => env('LARSASUB_CONNECT_FEE_ENABLED', false),
        'type' => env('LARSASUB_CONNECT_FEE_TYPE', 'percentage'),
        'value' => env('LARSASUB_CONNECT_FEE_VALUE', 10),
        'description' => env('LARSASUB_CONNECT_FEE_DESCRIPTION', 'Platform fee'),
    ],
    'tenant_label' => env('LARSASUB_CONNECT_TENANT_LABEL', 'organization'),
    'tenant_name_attribute' => env('LARSASUB_CONNECT_TENANT_NAME_ATTRIBUTE', 'name'),
    'tenant_owner_attribute' => env('LARSASUB_CONNECT_TENANT_OWNER_ATTRIBUTE', 'owner_id'),
    'authorize_route' => env('LARSASUB_CONNECT_AUTHORIZE_ROUTE', 'larsasub.mollie.connect.authorize'),
    'notifications' => [
        'also_notify_platform' => env('LARSASUB_CONNECT_ALSO_NOTIFY_PLATFORM', false),
    ],
    'disconnect_drain_days' => env('LARSASUB_CONNECT_DISCONNECT_DRAIN_DAYS', 30),
],

While Connect is on, boot fails when tenant_relation is empty, when client_id does not start with app_, and on a disconnect_drain_days that is not a positive whole number; it warns when client_id and client_secret are not both set. A fee.type other than percentage or fixed fails boot whether Connect is on or not.

Credentials and scopes#

The default scopes are payments.read, payments.write, refunds.read, refunds.write, customers.read, customers.write, mandates.read, mandates.write, profiles.read, organizations.read, onboarding.read and settlements.read. If you override the list, keep:

• onboarding.read, or MollieConnectService::getOnboardingStatus() fails with a 403 and stays null;
• refunds.read and refunds.write — without refunds.read no tenant refund ever completes in the package, not even one made in the Mollie dashboard; without refunds.write none can be requested (both warned at boot and by larsasub:doctor);
• settlements.read, or no tenant's payouts can be synced (warned at boot).

A tenant connected before a scope was added re-authorises to get it, through connect.authorize_route — see Re-authorising a connected tenant.

platform_organization_id lets the package skip application fees when a connected account is the platform's own organization — Mollie does not allow charging fees on your own account. The settlement sync uses it too, to tell the platform's own payouts from a tenant's.

Tenants#

• connect.tenant_owner_attribute must name a real attribute on your tenant model. The ownership check compares it with the signed-in user's key — a wrong name means the attribute is never set and nobody can manage the tenant.
• connect.tenant_name_attribute is read as a string (a Stringable is cast) and trimmed. Anything else — an int, an array, an empty value, or an accessor that throws (logged) — leaves the mail on config('app.name') and its admin button on the platform label.
• connect.tenant_context is called as __invoke(?\Illuminate\Database\Eloquent\Model $tenant): void. It receives the tenant stored on a registration, or null before a step for a registration without one (the platform billable, a simple-mode registration) — so its parameter must be nullable (?Model, or your own ?Tenant); a hook that cannot take null is a boot failure. On null, undo what the tenant branch does, without network I/O. A non-platform registration without a tenant while Connect is on gets null and then the tenant its owner's tenant_relation names — or, when it names none, the step is refused. Registrations only store a tenant in Connect mode (or when you pass it explicitly), so a hook set while connect.enabled is false only ever receives null for the ordinary ones; LarsaSub warns at boot. Leave it null when all billable models live on one database. See Multi-database tenancy.

Application fees#

With fee.enabled on, every tenant payment carries an application fee for the platform: percentage takes value % of the payment (rounded to cents), fixed takes value in the payment's currency, never more than the payment (a fixed fee of half the payment or more is logged). A fee under €0,01 is left off. A plan's own fee type and value, when set, take precedence over this block — even with fee.enabled off. No fee is charged on the platform's own billables (dual billing) or on an account that is the platform's own organization. See Application fees.

Disconnecting#

connect.disconnect_drain_days caps a requested disconnect: the account stays connected until every payment of the tenant has a final status, and is removed after this many days anyway, with what is still under way flagged for an operator. While it drains, nothing new starts for the tenant: no subscription, payment or retry. A SEPA debit settles within about five working days; the ceiling is for a claim that never resolves. The deadline is written at the request, so changing this moves no drain that runs. Drains end in the last pass of larsasub:execute-charges — see Disconnecting a tenant.

Settlements#

larsasub:sync-settlements mirrors Mollie's payouts and attaches each package payment to the payout it was paid out in, so a reference on a bank statement leads to its payments.

'settlements' => [
    'sync_platform' => env('LARSASUB_SETTLEMENTS_SYNC_PLATFORM', false),
    'platform_access_token' => env('LARSASUB_SETTLEMENTS_PLATFORM_TOKEN'),
    'platform_profile_id' => env('LARSASUB_SETTLEMENTS_PLATFORM_PROFILE_ID'),
],

Connected accounts are synced whenever Connect is enabled (they need the settlements.read scope). The platform's own account — the only one in simple mode, and where the platform's own charges settle under dual billing — only with sync_platform on.

That pass needs platform_access_token: Mollie serves the Settlements API to organization access tokens and OAuth tokens, never to an API key. Boot warns when the switch is on and the token is empty. Mollie also requires a profile id on that pass, so set platform_profile_id with it (warned when the token is set and the profile is not).

The frequency and look-back window live under Scheduling (sync_settlements_frequency, sync_settlements_lookback_days). See Settlements.

Email theme#

The colours of the package's mails. Mail clients do not support CSS variables, so these are written as inline styles and in the <style> block; the dark values apply through @media (prefers-color-scheme: dark) in the clients that support it.

'email_theme' => [
    'primary' => env('LARSASUB_EMAIL_PRIMARY', '#4077F4'),
    'primary_ink' => env('LARSASUB_EMAIL_PRIMARY_INK'),  // null = derived
    'light' => ['body_bg' => '#F8FAFC', 'card_bg' => '#FFFFFF', 'heading' => null, 'accent_text' => null, /* … */],
    'dark'  => ['body_bg' => '#0F172A', 'card_bg' => '#1E293B', 'heading' => null, 'accent_text' => null, /* … */],
],

The light and dark maps (config-file only):

The accent is three keys because it does three jobs: primary is the button surface, primary_ink is what is printed on it, and accent_text is the accent used as text — per mode, since a colour readable on the white card is often unreadable on the dark one. The role split, with the contrast figures behind it, is in Notifications.

Partial overrides are supported — only the keys you provide are replaced. Per-tenant theming is possible by implementing getEmailTheme() on the tenant model; its values are merged over these. Accepted values are hex colours (#RGB, #RRGGBB, with or without alpha), CSS colour names and rgb()/rgba()/hsl()/hsla(). Anything else is dropped — that element keeps the shipped default — and boot warns about it.

Quote hex values in .env. An unquoted # starts a comment, so LARSASUB_EMAIL_PRIMARY=#4077F4 sets an empty value. An empty value is treated as absent here, so the mail keeps the default — but not your colour.

If you published emails/layout.blade.php, primary_ink and accent_text reach your copy and not the package's — they are layout chrome, so a copy published before those keys existed does not read them and setting them does nothing. larsasub:doctor reports it; --tag=larsasub-email-layout re-publishes that one file.

Subscription rules#

Package-wide rules for how subscriptions are created and changed.

'subscription' => [
    'minimum_days_before_change' => env('LARSASUB_MIN_DAYS_BEFORE_CHANGE', 0),
    'max_notice_period_months' => env('LARSASUB_MAX_NOTICE_MONTHS', 1),
    'before_first_charge' => env('LARSASUB_BEFORE_FIRST_CHARGE'),
    'free_plan_mandate' => env('LARSASUB_FREE_PLAN_MANDATE', 'activate'),
],

minimum_days_before_change — individual plans can override it through Subscription.minimum_days_before_change; a plan's own value wins when set.

max_notice_period_months caps the notice period accepted when tenants define plans through the bundled dashboards, for both the cancellation and the renewal-cancellation notice period. A cancellation inside the notice window genuinely extends the contract and adds charges, so an oversized period is a money decision, not a display value. The default of 1 follows the strictest consumer rule in the package's home market (NL BW 6:236 sub j voids a longer period after silent renewal). It is one package-wide number — it cannot vary per tenant, plan or customer type, so raising it for B2B also drops the consumer-safe default for every B2C subscriber. null (or any non-numeric value) disables the cap. Validation-only: existing plans with larger values keep working (see Compliance).

before_first_charge — cost lines on the first charge#

An invokable class run right after a subscription is created and before its first charge is priced — the one moment cost lines can be put on a new subscription and still be collected by period 1. null (default) = no hook.

class AttachSelectedModules
{
    public function __invoke(BillableSubscription $subscription, ?BillableSubscription $previous = null): void
    {
        app(SubscriptionCostService::class)->reconcileLines(
            $subscription,
            $this->desiredModulesFor($subscription),
            ['module:']
        );
    }
}

• $previous is filled on the plan-change path only. It is both the discriminator (subscribe vs. change) and the data a re-adding host needs — the old subscription is already wound down by the time the hook runs, so querying backwards for it is not a contract. Gate on $previous === null to hook subscribes only.

• Fires on all three first-charge entry points: subscribe, subscribe with an existing mandate, and the plan change. It deliberately does not fire on createDeferredMandateSubscription(), where the documented contract is that the caller adds its own lines after creation.

• Code that calls the provider entry points itself can pass a ?Closure $beforeFirstCharge instead; an explicit closure always wins. This config key exists for hosts on the bundled dashboards, which have no call site to pass one through.

• On the bundled subscription dashboard, implement Contracts\ProspectiveCostLines as well. The subscribe card names the amount the click collects, and the lines this hook adds are part of it — but the hook runs inside the creating transaction, so nothing can simulate it. prospectiveLines($plan, $owner) states them beforehand (the shape addLine() takes); let __invoke() add exactly those on a new subscription, so there is one source:

  class AttachSelectedModules implements ProspectiveCostLines
  {
      public function prospectiveLines(Subscription $plan, Model $owner): array
      {
          return $this->modulesFor($owner, $plan);   // [['key' => 'module:x', 'description' => '…', 'amount' => 4.95], …]
      }
  
      public function __invoke(BillableSubscription $subscription, ?BillableSubscription $previous = null): void
      {
          if ($previous !== null) {
              return;   // the plan change: your own rule
          }
  
          $costs = app(SubscriptionCostService::class);
          foreach ($this->prospectiveLines($subscription->subscription, $subscription->billable->owner) as $line) {
              $costs->addLine($subscription, $line['key'], $line['description'], $line['amount'], $line['starts_on'] ?? null, billedThrough: $line['billed_through'] ?? null);
          }
      }
  }
  

  Without it the dashboard shows no subscribe button for any plan and refuses the subscribe, rather than name an amount that leaves the modules out; the boot log and larsasub:doctor say so. A headless host passes the lines to quoteFirstCharge() itself and does not need the contract.

• The package wraps the call in SubscriptionCostService::batch(), so one hook is one act — no half-finished totals are mailed to the subscriber, and the opening-composition rule keeps the whole set silent.

• It runs inside the creating database transaction: keep it cheap and DB-only, no external calls. A throw rolls the entire creation back (no subscription, no charge, no lines, no activation event) and the subscriber sees a generic translated message — never the host exception's own text.

• ConfigValidator and larsasub:doctor reject a class that does not exist, is not invokable, or whose __invoke() provably cannot take these arguments — at boot, because the alternative is a TypeError inside every subscriber's creating transaction. Declared, single, named types are judged; untyped parameters and mixed/object are not. A blank value (null, '', whitespace) means "off" and is never fatal; a value that is not a string is.

Adoption contract. Configuring this replaces an existing "re-add the modules" listener on BillableSubscriptionChangedEvent: the invokable fires on change too, so running both means an overlap-guard exception (same keys) or double-billed modules (different keys). While migrating, gate the old listener on blank(config('larsasub.subscription.before_first_charge')) — the resolver treats null, '' and a whitespace-only value alike as "no hook", so a strict === null would switch your listener off for an empty env variable while nothing took its place.

free_plan_mandate — what a free plan does about the mandate#

A plan with price_amount = 0 collects nothing, so its first charge is €0 and settles locally: the customer never passes a checkout, and no payment mandate is established. That is right for a plan that will never collect anything and wrong for one meant to grow cost lines later — the package cannot tell the two apart, so you choose.

Read the three values as one rule: is there already something to collect with? 'mandate' goes and gets one, 'refuse' declines the subscription, 'activate' shrugs. All three leave a subscriber who already holds a usable mandate alone, because the thing the key protects against — a free subscription with no way to collect cost lines later — is not the case for them. An unrecognized value is a boot failure, never a silent fallback to activate.

That is also why the two mandate-backed entry points (createSubscriptionWithMandate(), createDeferredMandateSubscription()) are never refused: both require a usable mandate by contract, and both run through the same shared BillableSubscriptionService::createSubscription() the guard lives in. If you want free plans gone altogether, retire the PLAN (active = false) rather than configuring 'refuse'.

Where 'refuse' is answered#

The guard sits in BillableSubscriptionService rather than in the provider layer: one level down the free subscription is already activated and its BillableSubscriptionActivatedEvent registered for the commit, so a refusal after that would leave an active subscription and a delivered activation mail behind a customer's error page. SubscriptionCostService::quoteFirstCharge() asks the same question and reports it as ChargeQuote::$creationRefused, so a checkout screen never names an amount for a subscription the next call throws on.

Where 'mandate' is answered — and where it is not#

'mandate' does not cover every entry point, and nothing tells you when it misses. It is answered in the provider layer — MollieService::createSubscription() — because the verification is a provider call, so it fires for the bundled subscribe flow and for anything going through PaymentProviderFactory::make(…)->createSubscription(). It does not fire for a host that calls BillableSubscriptionService::createSubscription() directly, nor on createDeferredMandateSubscription() (which is handed a mandate by contract) or a plan change that lands on a free plan. There is no exception, no redirect and no log line on those paths: the free subscription is simply activated without a mandate, exactly as under 'activate'. Nothing goes wrong until money is due on it — a cost line, an upgrade — and then there is nothing to collect with, which is the situation this setting exists to prevent.

Two consequences worth acting on:

• Headless hosts: subscribe through the provider service, not through BillableSubscriptionService, if you rely on this setting. The provider method delegates to the service anyway — it is the same subscription, plus the redirect this key is about.
• Or start the verification yourself where you create free subscriptions: PaymentProviderFactory::make(config('larsasub.provider'))->createMandateSetupPayment($owner, $method), which carries the same in-flight guard.

This is deliberately not a boot warning: which entry point a host calls is not readable from configuration, and the only proxy available — "no bundled dashboard is registered" — is wrong for precisely the headless host who does use the provider service.

'mandate' is idempotent in both directions: it does nothing when the subscriber already holds a usable mandate (there is already something to collect with, and a second verification is a second €0,01 plus a second mandate at their bank), and a verification that is still running is resumed rather than duplicated.

'mandate' guarantees the mandate exists, not that anything is collected. A free plan carries is_charged = false, which skips cost-line valuation entirely, so cost lines on such a subscription are still not billed. See Cost lines.

When the question cannot be answered#

All three values ask is there already something to collect with? in exactly one place (PaymentProviderService::billableHasUsableMandate(), tenant-scoped, never Billable::usableMandates()). Two things can make it unanswerable, and they are not the same asymmetry:

The first row is symmetric and cheap on both sides. The second is not: a broken provider registry stops free signups under 'refuse' while being invisible under 'mandate'. That is deliberate — refusing is the only thing the service layer can still do, and a host that configured 'refuse' asked for the cautious answer — but it is worth knowing before you debug "free plans suddenly refuse" without a provider error next to it. Both are still cheap next to the alternative, which is a free subscription that silently has nothing to collect with.

Dunning#

What happens to money that did not arrive or came back: follow-up charges after a chargeback, what a reversed chargeback does, and the reminder series.

'dunning' => [
    'chargeback_follow_up' => env('LARSASUB_DUNNING_CHARGEBACK_FOLLOW_UP', true),
    'chargeback_follow_up_methods' => ['directdebit'],
    'chargeback_follow_up_application_fee' => env('LARSASUB_DUNNING_CHARGEBACK_FOLLOW_UP_APPLICATION_FEE', false),
    'double_paid' => env('LARSASUB_DUNNING_DOUBLE_PAID', 'signal'),
    'chargeback_reversal_check_days' => env('LARSASUB_DUNNING_CHARGEBACK_REVERSAL_CHECK_DAYS', 60),
    'reminders' => [
        'enabled' => env('LARSASUB_DUNNING_REMINDERS_ENABLED', false),
        'since' => env('LARSASUB_DUNNING_REMINDERS_SINCE'),
        'steps' => [
            ['after_days' => 3, 'action' => 'notify'],
            ['after_days' => 10, 'action' => 'notify'],
            ['after_days' => 14, 'action' => 'escalate', 'notify' => false],
        ],
    ],
],

• chargeback_follow_up — a chargeback on a paid charge becomes a follow-up charge for the same period and VAT, payable by the customer through the manual payment flow and never collected from the mandate. On by default; LARSASUB_DUNNING_CHARGEBACK_FOLLOW_UP=false switches it off. Never retroactive: a chargeback delivered while it was off keeps no follow-up. See Recurring charges.
• chargeback_follow_up_methods — the provider method ids (PaymentMethod::provider_id) whose chargebacks get one. SEPA only by default: a SEPA storno is final, while a card chargeback is a dispute the merchant may still win; add creditcard only if you accept asking for payment while it runs. PayPal disputes run outside Mollie and are never seen. See Payment methods. [] means no method. Not a list of strings is a boot failure; an id that is no payment method here at all (a typo), and paypal, are larsasub:doctor warnings, checked once chargeback_follow_up is on.
• chargeback_follow_up_application_fee — Connect: charge the application fee again on the follow-up. Off: Mollie keeps the original's fee on a chargeback, so a second fee charges the tenant twice for one period. Turn it on only if the platform gives its fee back on a chargeback itself. See Connect.
• double_paid — the bank reversed a chargeback after its follow-up was paid, so the customer paid the period twice: signal (default; flag the follow-up needs_attention — the company mail, while that notification is on — and you give it back), refund (at Mollie from a queued listener with retries, normally on the original payment — which Mollie very likely refuses once it was charged back, and then it is flagged as with signal) or credit (wallet credit the refund ceiling counts). refund needs a real queue; on sync it runs inline in the webhook without retries. Anything else is a boot failure. See Recurring charges.
• chargeback_reversal_check_days — Mollie sends no webhook when a chargeback is reversed, so larsasub:execute-charges asks: it fetches the original payment of every follow-up whose chargeback is younger than this many days and not yet seen reversed, paid follow-ups included (default 60 — a card dispute is usually decided within that). 0 switches the daily look off; starting a payment on a follow-up asks Mollie first either way. Null or empty is the default; anything that is not a whole number of days is a warning and reads as the default. A config published before this key needs nothing: the default applies.
• reminders — the reminder series (Reminder series): after a collection failed or expired (or a retry the customer started was canceled at the checkout), or after a follow-up was created, the customer is reminded on the days in steps until the charge is paid. escalate tells your application through an event; the package never cuts off access by itself. It runs daily through larsasub:process-dunning (scheduling.process_dunning_frequency), so it needs the scheduler (boot warns while scheduling.enabled is off).

The reminder settings in detail:

• A config published before the reminder series existed has no reminders block, and only missing top-level keys are filled in: copy the block, or the env variable has nothing to switch on (Switching it on).
• since (Y-m-d) is the first day whose debts get a series — a failed collection by its planned date, a follow-up by the day it was created — so switching the series on for an install that ran for months does not escalate every old debt on day one. It is required once enabled is on; an empty or unparsable value is then a boot failure, a date in the future a warning.
• steps needs strictly increasing positive whole after_days (counted from the failure, or from the chargeback mail) and an action of notify or escalate. It takes no other keys than those and notify (true or false — optional, and never false on a notify step, which is the reminder itself; 'notify' => true on an escalate step sends a last reminder with the event). Anything else is a boot failure even while the series is off, because each case keeps the schedule it opened with — changing it only affects new cases. An empty schedule while the series is on is a warning.

Invoicing#

Automatic invoices and credit notes for paid charges, and the VAT rules that decide what gets collected. Override the InvoiceRenderer contract to plug in your own invoice system. See Invoicing and VAT.

'invoicing' => [
    'enabled' => env('LARSASUB_INVOICING_ENABLED', false),
    'vat_rate' => env('LARSASUB_INVOICE_VAT_RATE', 21.0),
    'prices_include_vat' => env('LARSASUB_PRICES_INCLUDE_VAT', true),
    'price_display' => env('LARSASUB_INVOICE_PRICE_DISPLAY', 'exclusive'),
    'country_display' => env('LARSASUB_INVOICE_COUNTRY_DISPLAY', 'name'),
    'seller' => [
        'name' => env('LARSASUB_INVOICE_SELLER_NAME'),
        'vat_number' => env('LARSASUB_INVOICE_SELLER_VAT'),
        'coc_number' => env('LARSASUB_INVOICE_SELLER_COC'),
        'address' => env('LARSASUB_INVOICE_SELLER_ADDRESS'),
        'country' => env('LARSASUB_INVOICE_SELLER_COUNTRY', 'NL'),
    ],
    'number_prefix' => env('LARSASUB_INVOICE_PREFIX', 'INV'),
    'credit_note_prefix' => env('LARSASUB_CREDIT_NOTE_PREFIX', 'CN'),
    'vat_validation' => [
        'enabled' => env('LARSASUB_VAT_VALIDATION_ENABLED', false),
        'validator' => null,              // class implementing Contracts\VatNumberValidator; null = VIES
        'recheck_after_days' => env('LARSASUB_VAT_RECHECK_DAYS', 30), // null = only on change
        'timeout' => 10,                  // seconds, per call
    ],
],

Off by default, deliberately. Invoices are numbered, legally relevant documents; turning this on is a conscious decision that comes with configuring the VAT rate and the seller details. A fresh install must never silently issue Dutch-VAT invoices with an empty seller. Boot warns while invoicing is on and seller.vat_number is empty.

VAT and prices#

A change of vat_rate reaches every subscription without a rate of its own or on its plan, from its next charge on. On exclusive prices for a customer who pays VAT, and for a zero-rated customer on inclusive ones, that moves the amount collected, and nobody is told: the package cannot observe a configuration change. A change of a plan's own vat_rate does mail the subscribers it affects (notifications.user.subscription_vat_rate_changed).

prices_include_vat is the single most consequential key here, because it changes what gets collected, not just what gets printed:

• true — price_amount includes VAT (B2C). Zero-rated customers (EU B2B reverse charge, outside the EU) are charged the net amount.
• false — price_amount excludes VAT (B2B), and VAT is added before collection: a 14,90 plan debits 18,03 domestically. Zero-rated customers pay the listed amount, and a customer without an invoice_country is not grossed up either — the package never adds VAT on a guess; the invoice then splits the collected amount instead.

Either way the invoice totals exactly what was settled. A single payment is the exception to the "listed price" reading: its amount is always what gets collected and is never grossed up. Read Invoicing and VAT before switching this on a live installation.

price_display and country_display are presentation only: stored invoice data is always net plus VAT, and the stored country code stays the source of truth for the VAT rules. An unknown country code always prints as the code; override the wording through larsasub::countries.{CODE}. Boot fails on any other value for either key. See Country codes and names and PDF price display.

Seller and numbering#

In Connect mode a tenant model that implements getInvoiceSellerDetails() supplies its own seller details per tenant. Numbers are sequential, never reset, and zero-padded to six digits; under Connect they carry the tenant's reference code in front ({TENANT}-INV-000001), also after the tenant disconnected. See Numbering.

VAT number validation#

Opt-in; off, nothing is called. On, every business profile with an EU number is checked after each change of type, country or number (a queued job, after the save commits — never inside it) and again every recheck_after_days by larsasub:check-vat-numbers (scheduling.check_vat_numbers_frequency, with scheduling.check_vat_numbers_delay_ms between calls and scheduling.check_vat_numbers_limit per run — see Command settings).

The outcome is stored, shown on the profile dashboard, and decides the reverse charge: on, only a number VIES confirmed is reverse charged, and a business customer in another member state whose number is not confirmed is charged VAT and reclaims it.

Check the numbers you already have before switching it on. Run php artisan larsasub:check-vat-numbers --unchecked first — it works while the check is off — or existing reverse-charged customers are charged VAT until their number is checked.

The requester is the seller's own VAT number — seller.vat_number, or the tenant's getInvoiceSellerDetails()['vat_number'] under Connect. Without one VIES still answers, but issues no consultation number.

Boot refuses a validator that is not a class implementing Contracts\VatNumberValidator, and a recheck_after_days that is neither null nor a positive whole number. It warns when the check is on while invoicing is off, when seller.vat_number is empty in simple mode, and on a timeout that is not a positive number (it reads as 10) or is not below the check job's own 60-second timeout. See Validating VAT numbers.

Reference codes#

The prefixes of the human-readable reference codes on charges and payments.

'reference' => [
    'first_payment_prefix' => 'FP',
    'recurring_charge_prefix' => 'RC',
    'single_payment_prefix' => 'SP',
    'mandate_setup_prefix' => 'MS',
],

Codes are formatted {PREFIX}-{8 chars}, e.g. FP-A7K3MX2P — or {TENANT}-{PREFIX}-{8 chars} in Connect mode, where the tenant's connected account carries a reference code. None of these keys has an environment variable.

Logging#

The log channel LarsaSub writes its own messages to — including the boot warnings.

'log_channel' => env('LARSASUB_LOG_CHANNEL', 'larsasub'),

The default larsasub channel — a daily log at storage/logs/larsasub.log, kept 14 days — is registered by the service provider unless config/logging.php already defines one; define it there for custom rotation or drivers. Set this to null or your app's default channel name to merge with the app log.

Table prefix#

'table_prefix' => env('LARSASUB_TABLE_PREFIX', 'larsasub_'),

Change it before running the migrations: the package does not rename existing tables.

Webhooks#

'webhooks' => [
    'rate_limit' => env('LARSASUB_WEBHOOK_RATE_LIMIT', '300,1'),
],

The throttle is the only brake on junk traffic against those unauthenticated endpoints, and every junk hit costs an outbound Mollie lookup. The default is deliberately generous: Mollie legitimately bursts from a small set of IPs on bulk settlement days, and a throttled-away webhook is a missed payment status until the provider retries.

Ngrok#

'ngrok' => env('LARSASUB_NGROK_DOMAIN', ''),

Development only: the value is used only while APP_ENV is local or development, and only for the provider's webhook URLs and the Mollie Connect OAuth callback URL, so Mollie can reach your machine. Otherwise those URLs are built from config('app.url'). A schemeless value gets https:// prepended.