Cbox Billing Revenue Recognition (plugin)

cboxdk/cbox-billing-revrec — ASC 606 deferred-revenue recognition for the Cbox Billing engine, as a drop-in plugin. It turns issued invoices and subscription terms into straight-line recognition schedules, exposes a deferred-revenue read model and a revenue waterfall, and lights up a gated Revenue console — data and UI in one package, with zero edits to the host.

It is deny-by-default: nothing recognises until the host both entitles the billing.revenue_recognition capability and wires a real recognizer. Left inert, the plugin books no revenue and the console area stays hidden.

What it adds

• Straight-line recognizer (StraightLineRecognizer) — spreads an invoice line's net evenly across the whole calendar months of its service period. The split is remainder-safe via the engine's Money::allocate() (largest-remainder), so a 1200-minor annual line recognises a clean 100/month, and a 1000-over-3 line splits 334 / 333 / 333 — the slices always sum back to the net, exactly. The default binding is the inert NullRecognizer.
• Recognition schedules (RevenueSchedule + RevenueScheduleEntry) — per invoice line: the billed total, the service period, and the period-by-period recognised amounts, persisted for review and reporting.
• Deferred-revenue read model (DeferredRevenueReader) — recognised-to-date versus remaining-deferred as of any instant (an entry recognises once its period has fully elapsed). recognised + deferred = total, always.
• Revenue waterfall (RevenueWaterfallReader) — recognised revenue per calendar period across every schedule, summed in integer minor units.
• Revenue console — a gated Revenue recognition page (waterfall + per-schedule detail) and a dashboard card (recognised this month / total deferred).

How it plugs in

• The console (nav, gate, dashboard card) plugs into laravel-console-kit, gated on the revrec feature — which is active only when the capability is entitled and a real recognizer is bound.
• Schedules are generated by calling the host-facing RevenueRecognizer service. The billing engine has no invoice-issued event, so the host invokes it from wherever it finalises invoices:

use Cbox\Billing\RevRec\Services\RevenueRecognizer;
use Cbox\Billing\RevRec\Support\ServicePeriod;

// Recognise every line of an invoice over the subscription term it covers.
app(RevenueRecognizer::class)->scheduleInvoice(
    $invoice,
    ServicePeriod::fromTerm($term, $invoice->issuedAt),
);

Install (SaaS)

composer require cboxdk/cbox-billing-revrec
php artisan migrate

Grant the capability and wire the recognizer to switch recognition on:

use Cbox\Billing\RevRec\Contracts\CapabilityGate;
use Cbox\Billing\RevRec\Contracts\RecognizesRevenue;
use Cbox\Billing\RevRec\Recognition\StraightLineRecognizer;

$this->app->bind(CapabilityGate::class, MyEntitlementGate::class);   // grants billing.revenue_recognition
$this->app->bind(RecognizesRevenue::class, StraightLineRecognizer::class);

Requires the Cbox Billing engine (cboxdk/laravel-billing) and a host console that has adopted laravel-console-kit.

License

MIT. © Cbox. Use, modify, redistribute and self-host freely — the only condition is keeping the copyright notice. See LICENSE.