Issue an invoice

POST /api/v1/billing/invoices prm_billing

Creates an invoice against a named subscriber from line items. discount and vat are percentages from 0 to 100, and the total is computed from the items — never taken from the request.

discount and vat are PERCENTAGES, and the validator rejects anything above 100. Sending 171.00 in the vat field to mean "171 in tax" is a 400, not a silently large invoice.

At a glance

Authentication: Staff token or session
Requires permission: prm_billing Billing & invoices
Rate limit: t_mutate

Parameters

Parameter	Description
`user_id`required body · integer	The subscriber being invoiced.
`items`required body · array	At least one line, each with name, qty, unit_price and an optional per-line tax.
`discount` body · number	Percentage from 0 to 100, not an amount.
`vat` body · number	Percentage from 0 to 100, not an amount.
`due_date` body · string	yyyy-MM-dd HH:mm:ss in UTC.
`mark_paid` body · boolean	Record the new invoice as already settled.

Errors

Code	When it is returned
`ERR_VALIDATION`400	user_id missing, no items, an unnamed item, or a discount or VAT outside 0 to 100
`ERR_NOT_FOUND`404	the subscriber does not exist or is outside the caller's subtree

Request

curl -X POST "$BASE/api/v1/billing/invoices" \
  -H "Authorization: Bearer $XR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": 4711,
  "description": "September installation",
  "discount": 0,
  "vat": 14,
  "due_date": "2026-10-01 00:00:00",
  "items": [
    { "name": "Router CPE", "qty": 1, "unit_price": 900.00, "tax": 0 },
    { "name": "Installation", "qty": 1, "unit_price": 250.00, "tax": 0 }
  ]
}'

BASE is your tenant host: the same address you sign in on.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us