How billing works
The objects and flow behind recurring revenue on VINR.
Billing composes a handful of objects — customers, products, prices, subscriptions, and invoices — into recurring revenue. Once you understand how they fit together and how money moves, every capability (trials, proration, usage, dunning, tax) is a variation on the same flow.
Core objectsAsk
| Object | What it answers |
|---|---|
customer | Who is being billed (shared with Payments). |
product | What you sell. |
price | How much and how often — e.g. €20 / month. |
subscription | The ongoing relationship that generates invoices. |
invoice | A statement for one billing period that Billing collects. |
// A product can have many prices (monthly, yearly, regional).
const product = await vinr.products.create({ name: 'Pro plan' });
const price = await vinr.prices.create({
product: product.id, // "prod_..."
amount: 2000, // €20.00
currency: 'EUR',
recurring: { interval: 'month' },
}); // "price_..."From price to invoice to paymentAsk
A subscription is the engine. On each cycle it does the same four things:
Generate a draft invoice
At the start of the period, the subscription creates a draft invoice with line items from its prices (and any usage or one-off invoice items).
Finalize
VINR applies discounts and tax, then finalizes — locking the invoice and computing the amount due.
Collect
The finalized invoice becomes a payment against the customer's default method. This is where Billing hands off to Payments.
React
VINR emits invoice.paid (or invoice.payment_failed, which triggers dunning). You fulfil access on the event.
Billing cycles & anchorsAsk
The billing cycle anchor is the moment each period begins. By default it's the subscription's creation time, so a subscription created on the 15th bills on the 15th. You can align cycles (e.g. everyone bills on the 1st) by setting an explicit anchor — VINR prorates the first partial period.
Changing quantity or price mid-cycle creates proration line items on the next invoice — credit for unused time and a charge for the new rate. See Trials & proration.
Where Payments fitsAsk
Billing decides what and when; Payments executes the collection. That separation means everything you configured in Payments — stored methods, SCA, retries, multicurrency — applies automatically to recurring charges. Failed collections flow into dunning rather than silently lapsing.
Where to go nextAsk
Products & prices
Model your catalog and pricing.
Subscriptions
The full subscription lifecycle.
Create a subscription
A runnable end-to-end guide.
Last updated on
