pushery/billing-for-laravel
pushery/billing-for-laravel is a Laravel package for adding billing and subscription features to your application, with configurable plans, invoicing, and payment handling for a lightweight, straightforward integration.
Architecture fit: The package now spans three domains rather than one. v0.45.0 established payments and marketplace plumbing (per-account drivers, per-account webhooks, Mollie Connect, account-scoped CSP and payment methods). v0.46.0 adds a subscription lifecycle engine — collection timing, mid-period proration, pause/unpause, direct debit mandates, consumer withdrawal — and a metered-usage and AI-spend subsystem with expiring grants, grace/debt balances, and daily caps. Architecturally it still fits a Laravel application that already relies on service providers, published config, migrations, scheduled artisan commands, queued jobs, and events. But a TPM should now treat the package as the system of record for revenue timing, not merely payment transport: it decides when money is collected, how partial periods are squared, what a paused subscriber can access, and what a consent record must contain. The new PausesSubscriptions and CollectsDirectDebits contracts follow the same container-bound extension pattern, so applications must supply bindings, persistence, and UI around them.
Integration feasibility: The headline breaking change is behavioral rather than structural, which makes it easy to under-scope. billing.collection_timing defaults to in_advance, so every new subscription on a package-billed driver is charged when a period begins — at the first billing:run after the mandate exists or at trial end — instead of at period end. The code diff is small; the finance, invoicing, dunning, and customer-communication consequences are not. Existing subscriptions keep the timing they started with (in arrears), so nothing running today changes, and the migration 2026_10_15_000163_add_collection_timing_to_billing_subscriptions_table records the new column. Everything else in the release is largely additive and opt-in, but it is additive in volume: six new migrations, new tables for mandate consents, direct debit notices, AI spend, expiring grants, plus paused_at. Applications not using metering, pause, direct debit, or AI spend can defer substantial portions, but must still run the migrations and consciously set the collection-timing variable rather than inherit the default.
Technical risk: High. The collection-timing default is the most consequential change in the release: it moves first revenue earlier, changes trial-conversion mechanics, alters cash-flow and revenue-recognition curves, and will generate "why was I charged before the period ended?" support volume. The mid-period swap/seat proration rules are genuinely intricate — a dearer tier or added seat is charged immediately as its own order and invoice after the owner's credit is spent; a cheaper tier or removed seat leaves credit capped by what the period's payment holds for that time; each tier is valued over its own interval; and a provider-refused charge does not undo the change but stays open until a later paid cycle. That is a lot of financial logic to validate without a deliberate test matrix. Pause semantics are also risky: access is granted only on unpause(), on package-billed drivers paused time is added to the current period, and a cancellation while paused ends the subscription at once. The SEPA direct debit work introduces IBAN validation, mandatory wording matched exactly to what the form displayed, a write-once consent record with notice period and confirmation provenance, and an erasure path that unlinks it — that is PII and legal exposure, not just a form. The Stripe webhook change is quietly significant in the other direction: missing invoice.upcoming could delay usage onto an invoice by a full cycle with no error, and only billing:doctor (plus StripeWebhookEventMapper::EVENT_TYPES / StripeMarketplaceWebhookEventMapper::EVENT_TYPES for deployment scripts) surfaces the gap. Two further hazards: invalid environment values for metering backoff/stall/grace and Mollie timeouts/retries silently fall back to shipped defaults, so a typo produces no failure signal; and the release notes are truncated mid-sentence at the § 312k BGB cancellation button, so the full scope of that addition and any remaining breaking changes cannot be confirmed from this excerpt.
Key questions:
BILLING_COLLECTION_TIMING, or accept the in_advance default, and has finance signed off on the revenue-recognition and cash-flow change?billing.ai.rates dated entries maintainable by someone other than engineering?billing:usage:flush scheduled every minute, and what happens to expired-grant write-offs and debt balances if it is not?billing:doctor wired into the deploy pipeline for every package webhook endpoint, including connected-account endpoints?AT, DE, LI, LU cover them, or do we need a custom SepaMandateWording with legal review?CancellationButton::declare() / DeclaredCancellation content require?Stack fit: Strong, but the package is now scheduler- and queue-centric in a way it was not before. Correct operation depends on billing:run for advance collection, a per-minute billing:usage:flush for expired grants, the daily money-back reconciliation, queue workers using the BILLING_MOLLIE_ACCOUNT_BACKGROUND_* client while web requests use the separate BILLING_MOLLIE_ACCOUNT_REQUEST_* settings, and billing:doctor as a verification gate. Applications that treat Laravel scheduling as an afterthought will not get the intended behavior. Prefer environment variables for the metering and Mollie client tunables rather than publishing config, but validate them at deploy — an unparseable value keeps the shipped default with no warning.
Migration path: Pin to an exact 0.x version and upgrade in staging. Sequence the code change ahead of the behavioral change: apply the migrations, confirm existing subscriptions retain arrears timing, then set collection timing deliberately per environment and pilot on a single tenant. Build a proration test matrix before enabling mid-period changes — dearer, cheaper, add seat, remove seat, tier with a different interval, and a provider-refused charge that must remain open. For pause, verify access is actually withheld and that resumption adds the paused time back on package-billed drivers. For direct debit, implement CollectsDirectDebits, render DirectDebitMandates::text() for the payer's country and persist exactly the text shown, handle DirectDebitMandateRefused reasons as field-level form errors, and confirm the erasure path unlinks consent records. For metering, set billing.ai.rates with dated entries, define billing.ai.daily_caps and owner_daily_cap, and decide which meters get grace and how debt is surfaced to customers.
Compatibility: Pre-1.0 with an explicit breaking change. Runtime signatures are largely stable; the break is in default billing behavior and therefore in invoice timing, dunning, and customer expectation. Running subscriptions are explicitly protected, so compatibility risk is concentrated in subscriptions created after upgrade. New tables and columns are additive but required. New contracts are only binding if the corresponding features are adopted. Environment-driven tuning is weakly validated by design, which is a compatibility trap for anyone assuming a bad value fails loudly. The release notes are incomplete, so residual breaking changes should be assumed possible until the full notes are read.
Sequencing: 1) Obtain the untruncated release notes and confirm the Laravel/PHP support matrix for v0.46.0. 2) Decide BILLING_COLLECTION_TIMING with finance and document the customer-facing explanation. 3) Inventory package-billed drivers, mid-period change flows, pause requirements, direct debit markets, and metered/AI usage. 4) Review and stage all new migrations with a rollback plan. 5) Upgrade in staging; validate proration, pause/unpause, direct debit refusal paths, expired-grant flush, and AI cap enforcement against provider sandboxes. 6) Run billing:doctor against every package webhook endpoint and reconcile event subscriptions before enabling traffic. 7) Deploy behind tenant-level flags, starting with a single pilot in advance mode. 8) Enable direct debit and § 312k cancellation handling only after legal review of wording and consent retention. 9) Turn on metering caps, grace, and the per-minute flush with monitoring, then hand over runbooks.
Maintenance: Expect a materially larger upkeep surface. Finance-adjacent maintenance now includes the AI rate table with dated per-model entries priced in millionths of the currency, mandate wordings per country, daily and per-owner spend caps, prepaid-versus-grant consumption ordering (expiring grants first, then prepaid, with grant-covered usage netted before the provider is told), and grace/debt limits. Engineering maintenance covers six new migrations, a per-minute scheduled flush, billing:doctor in CI, webhook event-type parity for platform and connected-account endpoints, and validated environment variables for metering and Mollie clients. Legal and compliance maintenance covers SEPA consent retention, notice periods, and erasure. None of this is heavy individually; together it turns a payments package into a subsystem with a real operational owner.
Support: Support needs new runbooks beyond the v0.45.0 set: "charged at the start of the period" explanations for advance collection, mid-period proration invoices and credit balances, refused proration charges that remain open, pause versus cancel semantics and why access stops on pause, cancellation while paused ending immediately, DirectDebitMandateRefused reason codes mapped to form fields, mismatched mandate wording, AI daily-cap refusals, expired-grant write-offs (usage.grant_expired), and debt balances from grace overage. billing:doctor output should become a first-line diagnostic for silent webhook gaps. Support will also need a story for SubscriptionPaused and SubscriptionUnpaused events, since applications use them for their own locks and notices.
Scaling: Advance collection increases order and invoice volume, because mid-period swaps and seat changes generate their own orders rather than being netted at period end — plan for more documents per customer per period and for reconciliation that matches them. Metered usage adds a per-minute job whose cost scales with the number of expiring grants and balance rows, and the AI spend table grows per call with per-provider and per-owner daily counters that must remain atomic under concurrency. Multi-tenant and marketplace scale still means per-account clients, webhook secrets, CSP sources, and event streams, now compounded by each connected account needing the full declared Stripe event set. A platform-level endpoint missing one event type silently degrades a whole feature, as invoice.upcoming did.
Failure modes: The highest-risk failures are: a customer charged earlier than expected because the advance default was never consciously chosen; a downgrade credit mis-applied or a mid-period change that leaves an open charge nobody collects; pause failing to revoke access, or resuming without restoring the paid days; a direct debit mandate registered with wording that differs from what the form displayed, producing a refusal or an invalid consent; consent records surviving erasure improperly; billing:doctor never run so a webhook endpoint quietly lacks a required Stripe event type; billing:usage:flush unscheduled so expired grants are never written off and debt never repaid; a mistyped metering or Mollie timeout variable silently reverting to defaults; spend brakes allowing concurrent calls past the cap; and the truncated notes hiding an unaddressed breaking change around the BGB cancellation button.
Ramp-up: High. Engineering needs time for migration review, proration and pause correctness, and the direct debit contract implementation. Finance needs to sign off on advance collection and understand proration credits and open charges. Legal and compliance need to review mandate wording, consent retention, and the § 312k cancellation flow. Support needs training across subscriptions, mandates, and metered spending rather than payments alone. Operations needs the per-minute scheduler, billing:doctor gating, environment validation, and monitoring for flush failures and cap refusals. A TPM should insist on a single-tenant pilot in advance mode, a written proration test matrix, sandbox direct debit refusals, and webhook event parity verification before broad rollout.
How can I help you explore Laravel packages today?