How Subscriptions Work in VBWD: Plans, Billing Periods, Trials, and Invoices

A technical tour of subscription billing in VBWD: plans as data, multi-currency pricing, trial-to-paid conversion, a token allowance for metered usage, and an invoice lifecycle with per-line tax that reconciles.

Subscriptions are where a lot of products quietly break; here is how VBWD models plans, billing periods, upgrades, trials, tokens and invoices as one engine you configure rather than build.

The short version

In VBWD, a subscription is a small set of moving parts — a plan, a billing period, an optional trial, and an invoice — that are configured as data rather than baked into the codebase, so you can change what you sell without shipping a new build.

Subscription is a plugin, not the core

VBWD keeps a deliberate separation. The core platform owns three durable concepts: the user, the authentication token, and the invoice. Everything specific to recurring commerce — plans, subscription lifecycle, entitlements — lives in a subscription plugin. That boundary matters in practice: it means the billing logic can evolve, be swapped, or be disabled entirely without touching account management or invoicing.

Payment providers sit behind the same kind of seam. Each provider implements a lifecycle interface, so billing decides what a customer owes and the payment plugin decides how that amount gets collected. You can read more about how the platform is assembled from these swappable parts on the plugins overview.

Plans are data you edit in the admin app

A plan in VBWD is a record, not a class. It carries a name, a price, a currency, a billing period, and a set of limits or entitlements. Because a plan is stored data, you create and adjust it in the admin app — change a price, add a tier, tighten a limit — and the change takes effect without a deploy.

That has a real operational consequence. Pricing experiments, regional plans, and promotional tiers become a configuration task for whoever runs the business, not a ticket for whoever runs the servers. VBWD supports tiered plans, per-plan billing periods, and add-ons layered on top of a base plan. The public pricing model is built on exactly this mechanism.

Billing periods and the recurring charge

The billing period on a plan defines the cadence — monthly, yearly, or whatever interval you configure. VBWD does not silently poll for due charges in the background as a side effect of a page load. Instead, a billing command drives recurring charges: it scans for subscriptions that are due, converts trials that have reached their conversion point, and produces the charges that follow.

Running that step as an explicit command rather than a hidden timer is a practical choice. You can schedule it, run it manually while testing, and reason about exactly when money moves. It also keeps the trial-to-paid transition observable, because conversion happens inside the same predictable pass.

Trials and how conversion happens

A plan can start a customer in a trial. During the trial the customer holds the plan’s entitlements without being charged. When the trial reaches its end, the recurring billing pass is what converts the subscription from trial to paid and issues the first real charge — the customer does not sit in an ambiguous state waiting for a webhook to guess their status.

Upgrades, downgrades, and cancellations are first-class transitions on the same subscription record. A downgrade changes the entitlements the customer will hold going forward; a cancellation stops future charges. Because entitlements are tied to the plan the subscription currently points at, the effect of a change is a matter of which plan record is in force.

Tokens: metering usage on top of a plan

Not every feature is priced by a flat monthly fee. VBWD includes a token, or credit, system for metering consumption — the natural fit for AI features and anything where usage varies wildly between customers. A plan can grant a monthly token allowance, and when a customer exhausts it they can buy more. The allowance resets on the plan’s cadence; the top-ups are one-off purchases that flow through the same invoicing path as everything else.

This lets a single subscription combine a predictable recurring fee with pay-as-you-go headroom, without turning every AI call into a separate billing relationship. Which features meter tokens and which are flat is, again, a matter of plan configuration. The features page catalogues what the platform meters this way.

Invoices, line items, and tax that reconciles

When money is owed, VBWD produces an invoice, and the invoice is where the accounting rigor lives. An invoice carries line items, and each line item carries its own per-rate tax breakdown rather than a single blended tax figure stapled to the total. Prices flow through a unified price model — a value object that holds an amount, a currency, and that per-rate tax breakdown — and it is never rounded mid-calculation. Rounding happens at presentation, not in the middle of a sum, which is how multi-currency totals stay correct instead of drifting by a cent per line.

Discounts are handled honestly. A discount is a line item that carries a negative per-rate tax breakdown, so when the invoice sums its lines the tax reconciles automatically — the discount removes both the net amount and the tax that was applied to it, per rate, with no special-case arithmetic. The details of how these totals are assembled are documented on the billing pages.

Payment is an event, and other features listen

When an invoice is paid, VBWD fires an event. This is the hinge that connects billing to the rest of the system. Payment providers — Stripe, PayPal, YooKassa — run through a swappable adapter plugin, so the collection mechanism is decoupled from the fact of payment. Once payment is confirmed, the event lets other features react: entitlements activate, token allowances refresh, and outbound webhooks notify external systems.

Because reactions are wired to an event rather than hardcoded into the payment handler, adding a new post-payment behavior means subscribing another listener, not editing the collection path. That keeps the risky part — taking money — stable while the reactions around it grow.

A worked example

Suppose you sell an AI-assisted tool on a monthly plan with a 14-day trial and a monthly token allowance, plus an add-on for extra seats.

1. Admin creates "Pro" plan: monthly period, price + currency,
   token allowance, entitlements. No deploy.
2. Customer signs up -> subscription starts in trial.
   Entitlements active, no charge.
3. Customer adds the "extra seats" add-on -> layered on the plan.
4. Day 14: billing command runs -> trial converts to paid.
   An invoice is generated:
     - line: Pro plan          (net + per-rate tax)
     - line: extra-seats add-on (net + per-rate tax)
     - line: launch discount    (net + NEGATIVE per-rate tax)
   Totals reconcile because tax is tracked per line, per rate.
5. Payment adapter (e.g. Stripe) collects the amount.
6. invoice.paid event fires -> token allowance refreshes,
   entitlements confirm, outbound webhook notifies your CRM.
7. Next month: billing command runs again, new invoice, repeat.
   Mid-cycle upgrade? The plan the subscription points at changes;
   the next pass bills the new plan.

Every step above is either a data edit or a scheduled command. The parts of the flow specific to your business are plan records; the parts specific to VBWD are the invoice, the event, and the adapter interface.

Honest limits

This model asks something of you in return for its flexibility. Recurring charges run when the billing command runs — you are responsible for scheduling it reliably, because there is no hosted cron doing it for you. VBWD is self-hosted and source-available under the Business Source License 1.1: free for commercial use until VBWD-attributable annual sales exceed the value of 6.7 BTC, after which a commercial license applies, and the license converts to Apache-2.0 on its change date. It is not public domain, and it is not a hands-off SaaS — you run the Python/Flask, PostgreSQL, Redis, and Vue stack yourself, in Docker.

Proration, dunning depth, and tax jurisdiction coverage are only as complete as the plan data and payment adapter you configure; VBWD gives you the reconciling primitives, not a pre-filled tax engine for every country. The operational reference for these edges lives in the docs.

Takeaway

VBWD treats a subscription as configuration plus a few disciplined primitives: plans you edit as data, a billing command you schedule, invoices whose per-line tax reconciles by construction, and a payment event other features hang off. Because it is self-hosted, you own the customer and billing data outright, the architecture stays GDPR-friendly, and no platform takes a cut of your transactions. You trade a managed service for control — and if your billing needs are specific, that trade is usually the point.