Line items & tax
Compose amounts, quantities, discounts, and tax.
Every invoice is the sum of its line items. This page explains how VINR assembles those items from subscription prices, metered usage, and one-off charges, then layers discounts and tax on top to compute the final amount due.
What a line item isAsk
A line item is a single billable row on an invoice. Each one carries an amount, an optional quantity, and a reference to where it came from. When an invoice finalizes, VINR sums the line items, applies invoice-level discounts, computes tax, and locks the total.
| Line item source | type | Created by |
|---|---|---|
| Recurring subscription price | subscription | The cycle that owns the subscription |
| Metered usage | usage | Aggregated usage records at period close |
| One-off charge | invoice_item | You, via the API before finalization |
| Proration adjustment | proration | A mid-cycle quantity or price change |
Prop
Type
How an invoice is assembledAsk
Collect pending items
When a billing period closes, VINR opens a draft invoice and pulls in every subscription price, any aggregated usage, and any pending one-off invoice items attached to the customer.
Apply discounts
Coupons and discounts reduce the subtotal. A percentage coupon applies across all eligible line items; a fixed-amount coupon reduces the subtotal once. Discounts always apply before tax.
Compute tax
VINR resolves the tax rate from the customer's address and the tax behavior of each line item, then adds a tax line item per jurisdiction. With inclusive behavior the displayed amount already contains tax; with exclusive behavior tax is added on top.
Finalize and total
The invoice locks. amount_due = subtotal − discount + tax. No further line items can be added once finalized.
Adding a one-off chargeAsk
Attach an invoice item to a customer and it lands on their next draft invoice — or on a standalone invoice you create explicitly.
import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });
// A one-off setup fee, taxed exclusively, added to the next invoice.
const item = await vinr.invoiceItems.create({
customer: 'cust_8Qd2',
amount: 4900, // EUR 49.00
quantity: 1,
currency: 'EUR',
description: 'Onboarding setup fee',
tax_behavior: 'exclusive',
}); // "mbu_..." -> resolves to an invoice itemTo preview the assembled total before charging the customer, retrieve the upcoming invoice. This runs the full assemble-discount-tax pipeline without finalizing.
const preview = await vinr.invoices.upcoming({ customer: 'cust_8Qd2' });
console.log(preview.subtotal); // sum of line items, before tax
console.log(preview.tax); // computed tax total
console.log(preview.amount_due); // subtotal - discount + tax
for (const line of preview.lines) {
console.log(line.type, line.description, line.amount, line.quantity);
}Tax behavior in practiceAsk
tax_behavior decides whether a line item's amount is gross or net.
A EUR 100.00 line item at 20% VAT produces a EUR 20.00 tax line. The customer pays EUR 120.00. Common for B2B invoicing where prices are quoted net.
A EUR 100.00 line item at 20% VAT already contains EUR 16.67 of tax. The customer pays EUR 100.00; the tax line is informational. Common for B2C catalogs with tax-included pricing.
Set a customer's tax_exempt flag to reverse for EU reverse-charge or exempt for non-taxable entities. VINR then emits a zero-rated tax line with the reason recorded for your records.
Resulting eventsAsk
| Event | When it fires |
|---|---|
invoice.created | A draft invoice opens and line items are attached. |
invoice.finalized | Discounts and tax are computed; the total is locked. |
invoice.paid | Collection against the customer's default method succeeds. |
Verify the signature on every webhook before trusting its contents.
const event = vinr.webhooks.verify(payload, request.headers['x-vinr-signature']);
if (event.type === 'invoice.finalized') {
const inv = event.data.object; // "inv_..."
console.log('Locked total', inv.amount_due, inv.currency);
}Edge casesAsk
Next stepsAsk
Tax
Configure rates, jurisdictions, and exemptions.
Coupons & discounts
Reduce the subtotal before tax.
Usage-based billing
Turn metered usage into line items.
Last updated on
