Docs / Reports and billing

Billing

Onyx Voice can price outside calls and add up a monthly bill per tenant: call charges from a rate plan plus monthly fees. This chapter covers rate plans and their CSV files, which calls are priced and on what number, a tenant's plan and fees, the monthly bill and its CSV, and re-rating. It is meant for a reseller or a hosting provider that charges companies for their phone service, or for an IT department that charges calls back to departments run as tenants.

Onyx Voice works out the bill; it does not send invoices or take payments. Download the CSV and put it into your accounting or invoicing system.

Who sees what

• A system administrator sees the whole Billing page: the bill of every tenant, the rate plans, and the plan and fees of the tenant picked at the top of the console.
• A tenant administrator sees only their own tenant's bill: what the phone system costs this month in outbound calls and fees. They cannot see or change rate plans or fees.

How calls are priced

Only outbound calls to a carrier are priced: any call leg that leaves on a trunk. That includes calls your users dial to outside numbers, calls forwarded to an outside number, outside numbers in ring groups and queue callbacks. Incoming calls and calls between extensions cost nothing. A call that is not answered costs nothing.

Each call is priced when it ends, with the tenant's rate plan at that moment:

1. The number. The call is priced on the number the server sent to the carrier: after your outbound route removed or added digits and after the trunk's Send numbers as format, without the trunk's Dial prefix, digits only. When the server's Country tones setting is the United States or Canada, a 10-digit number gets its leading 1, and the 011 exit code is dropped, so 6125550100, 16125550100 and +16125550100 are all priced as 16125550100, and 011 44 20 7946 0000 as 442079460000.
2. The rate. The longest prefix of the plan that matches the number wins. With rates for 1 (North America) and 1800 (US toll free), a call to 1 800 555 0100 matches 1800.
3. The price. The connect fee, plus the per-minute price for the talk time rounded up to the rate's billing increment, and at least the rate's minimum.

For example, a rate of 0.02 per minute with a 6-second increment, no minimum and no connect fee prices a call of 1 minute 31 seconds as 96 seconds: 0.032. With a 60-second increment the same call is billed as 2 minutes: 0.04.

A priced call with no matching rate costs 0 and is listed on the bill under "No matching rate", so you can see what your plan is missing. A tenant without a rate plan has no call charges, and its calls are not counted on the bill.

Outside the United States and Canada the number is priced as it was sent, digits only. Write your prefixes in the same form your trunks send numbers (for example international format, which you can choose under the trunk's Send numbers as), or the rates will not match. See Trunks (carriers).

The price of each outbound call shows in a Cost column in Call history once any call in the list has one. See Call history and reports.

Rate plans

A rate plan is a price list with a currency. Several tenants can share one plan.

To create a plan:

1. Open Billing and click New plan in the Rate plans card.
2. Enter a Name (up to 60 characters, for example "Standard US") and the Currency, a three-letter code such as USD, EUR or GBP.
3. Click Create plan, then import its rates.

The Rate plans card lists each plan with its number of rates, the number of companies using it and its currency, and these buttons:

• Rates shows the plan's rates (the first 300): Prefix, Destination, Per minute, Connect and Billing (the increment and minimum).
• Import loads rates from a CSV file.
• Export downloads the plan's rates as CSV.
• Delete removes the plan (click again to confirm). Tenants using it are left without a plan, so their calls are no longer priced.

The rate CSV

To import rates:

1. Click Import on the plan.
2. Choose the CSV file.
3. Tick Replace all rates of this plan to start from an empty plan. Without it, rows for a prefix the plan already has replace that rate, and the other rates stay.
4. Click Import. The console says how many rates were imported and how many rows were skipped.

The file needs a header row. Columns can be in any order:

Rows without a usable prefix or price are skipped. An example:

prefix,description,per_minute,connect_fee,increment,minimum
1,USA and Canada,0.012,0,6,6
1800,US toll free,0,0,60,0
1876,Jamaica,0.18,0,60,60
44,United Kingdom,0.025,0,60,0
447,United Kingdom mobile,0.09,0,60,0

Export writes the same six columns, so you can export a plan, change prices in a spreadsheet and import it again. Many carriers publish their rate decks as CSV; rename the columns to the ones above, or to one of the accepted names.

New and changed rates apply to calls that end after the change. To apply them to calls already made, re-rate the month (below).

A tenant's plan and fees

To set what a company pays:

1. Pick the tenant at the top of the console and open Billing.
2. In the card headed with the tenant code and "plan and fees" (for example acme: plan and fees), choose the Rate plan, or No rate plan (calls are not priced).
3. Enter the Monthly fee, the fee Per extension and the fee Per phone number, in the plan's currency.
4. Click Save.

New calls use the new plan straight away. Saving does not change calls already priced; use Re-rate for that.

The fees on the bill are:

• Monthly fee, once per month.
• Per extension times the number of user extensions in service.
• Per phone number times the number of routed phone numbers (DIDs). A catch-all route for everything else on a trunk does not count.

The counts are taken as they are when you look at the bill, not as they were during the month. Look at (and download) a month's bill soon after it ends if you add and remove extensions often.

The monthly bill

The Bill for card shows one row per tenant for a month. Months follow each tenant's time zone. To see another month, pick it in the month box and click Show. The columns are:

Click Details on a row for that company's calls by destination: the rate's description and prefix, the number of calls, minutes and charges, the most expensive first. Calls that matched no rate are grouped as "No matching rate".

The bill CSV

Click CSV in the Bill for card to download the month's bill (all tenants for a system administrator, your own tenant otherwise). The file is named after the month, for example bills-2026-10.csv, with these columns:

tenant,name,plan,currency,extensions,dids,outbound_calls,billed_minutes,call_charges,monthly_fee,extension_fees,did_fees,total

billed_minutes is the talk time of the priced calls, not rounded to the rates' increments. Amounts have two decimals. Each row carries its own currency: tenants on plans in different currencies are not added together.

Re-rating

Re-rating prices a month's calls again with today's rates and the tenant's current plan. Use it after you fix a rate, import a new rate deck, or give a tenant a plan for calls it already made.

1. Pick the tenant at the top of the console and open Billing.
2. Show the month you want to re-rate in the Bill for card (pick it and click Show).
3. In the tenant's plan card, click Re-rate followed by the month, for example Re-rate 2026-09.

The console says how many calls were priced again. Re-rating a tenant that no longer has a plan clears its call charges for that month. There is no undo, so download the bill CSV first if you might need the old figures.

Billing from the command line

onyx billing plans
onyx billing plan add "Standard US" --currency USD
onyx billing rates import "Standard US" rates.csv --replace
onyx billing rates export "Standard US" > rates.csv
onyx billing tenant acme --plan "Standard US" --fee-monthly 25 --fee-per-extension 4.50 --fee-per-did 1.50
onyx billing tenant acme --plan none
onyx billing bill 2026-09
onyx billing plan delete "Standard US"

onyx billing tenant changes only the options you give. onyx billing bill prints every tenant's bill for a month (this month when you leave the month out), with the totals in each tenant's currency. Re-rating is only in the console. See Command line (onyx).