Billing each client

All clients make calls through 1 account at Telnyx, the telephone carrier. Until 19 October 2026 the Telnyx invoice had 1 line. Thus nobody could see the cost of each client. This page explains the 3 Telnyx objects that each client now gets. It explains how the platform creates them and how you read the invoice. The page tells you when you must work in the Telnyx portal.

The problem

All clients make calls through 1 Telnyx account. Telnyx sends 1 invoice with 1 line. LeadRefinery could not see the cost of each client. Thus LeadRefinery could not bill each client for its own calls.

The idea in one sentence

Telnyx can split its invoice into billing groups. A billing group is a label on the invoice. Each client gets its own billing group. The client's call minutes and its number rent both go to that group.

The 5 objects in Telnyx

Telnyx has 5 kinds of objects that matter here. Each object has 1 job:

Two facts shape the design:

1. Call minutes go to the billing group of the voice profile that made the call. They do not go to the billing group of the phone number. Only the rent follows the phone number.
2. One voice application has exactly 1 voice profile.

Thus 1 shared voice profile sends all minutes to 1 billing group, whatever tags the phone numbers carry. To split the minutes, each client needs its own voice profile. To get its own voice profile, each client needs its own voice application.

What each client gets

Each real client gets 3 objects. All 3 objects have the same name. The name holds the environment and the client's short name, for example lr-production-acme:

• A billing group. This is the client's line on the invoice.
• A voice profile. The minutes follow the voice profile. A shared voice profile is a shared invoice line.
• A voice application. A call can use a voice profile only through a voice application. A voice application has 1 voice profile. The new voice application sends the call events to the same web address as before. Thus nothing else changes.

The name is a label. The platform stores the id of each object, and the money follows the id. If you change the client's short name, the platform renames the 3 objects and re-tags the client's phone numbers. The invoice history stays on the same billing group.

The old shared voice application stays. It is the fallback for clients without objects: the demo clients and the test clients. Their minutes go to "no billing group". This is correct, because these minutes are LeadRefinery's own cost.

The platform creates all of this

Nobody does this in the Telnyx portal. An admin presses Create organization on the Organizations page of the control room. Then the platform does 5 steps:

1. The platform creates the client's record.
2. The platform creates the billing group in Telnyx.
3. The platform creates the voice profile and binds it to the billing group.
4. The platform creates the voice application and binds it to the voice profile.
5. The platform stores the 3 object ids on the client's record.

The Dialling tab of the client shows the 3 ids under Telnyx billing. The voice application picker already shows the new voice application. You can still change the picker.

The step follows 5 rules:

• Demo clients get nothing. They call through the shared demo line, on LeadRefinery's invoice.
• A developer's laptop creates nothing. The step is off without a Telnyx key. The step is also off when the environment setting is "local". A laptop must not create objects in the shared account.
• A Telnyx failure does not block the create. The platform creates the client. The Dialling tab shows the error and a Create Telnyx objects button. Press the button to run the step again.
• The step is safe to repeat. The step looks for the stored ids first. Then it looks for objects with the client's name. It creates only the missing objects.
• The step also binds the phone numbers already in the client's pool. Each pooled phone number gets the billing group, the voice application and the client tag. The step skips retired phone numbers.

You still buy phone numbers by hand

You buy phone numbers in the Telnyx portal, as before. In the Telnyx portal you give the phone number 1 tag: the environment tag, env-production or env-staging. Since 12 October 2026 the picker on the Dialling tab lists only the phone numbers with the tag of this environment. You cannot pool an untagged phone number.

You do not set a billing group, and you do not assign the phone number to a voice application. The platform does both when you add the phone number to a client's number pool.

When you add a phone number to a client's pool on the Dialling tab, the platform sends 1 update to Telnyx for that phone number. The update sets 3 things:

• The billing group. The rent of the phone number goes to the client's invoice line.
• The voice application. A lead who calls the phone number back reaches the client's voice application.
• Two tags. The first tag is the environment tag, which the phone number already has. The update sends it again, because Telnyx replaces the full tag list. The second tag is a client tag. The client tag lets you filter the client's phone numbers in the Telnyx portal. It does nothing more.

When you remove an unused phone number from a pool, the platform resets the phone number. The phone number keeps the environment tag only, with no billing group. The phone number stays in the account, free for the next client.

Do not share a phone number between 2 production clients. A phone number has 1 billing group. Thus nobody can split the rent of a shared phone number.

Staging and production in one account

One Telnyx account serves staging and production. Telnyx has no concept of an environment. Thus LeadRefinery marks the environment itself:

• The environment setting. Each deployment has 1 environment setting. Staging has "staging". Production has "production". Nobody sets it per client or per phone number.
• The environment tag on a phone number. You set this tag in the Telnyx portal when you buy the phone number. The picker of each environment lists only the phone numbers with its own tag. You cannot pool an untagged phone number or a phone number with the tag of the other environment. To look at a phone number in the picker changes nothing.
• The voice application and the voice profile also carry the environment. Telnyx cannot tag a voice application at creation. Thus the name holds the environment: the production name and the staging name differ. The voice profile carries the environment tag.

The environment tag is only a lock. It stops the staging deployment from pooling a production phone number. It does not route calls. It does not split money.

The account holds 2 more environments next to staging and production: the demo line and local development. Each of the 4 has its own voice application, voice profile and API key. One webhook key serves the whole account. How the platform uses Telnyx lists the 4 and the settings they share.

How many calls at the same time

Telnyx has 3 limits on calls at the same time, in this order:

1. The account limit. One number for the full Telnyx account, across every voice profile and voice application. A new account gets 2. A verified account gets 10. For more, you must send a request to Telnyx support. The error "User channel limit exceeded (D1)" shows this limit.
2. The voice profile limit. Optional, per voice profile. It must be at or below the account limit. With 1 voice profile per client, each client can get its share. LeadRefinery does not set it today.
3. The voice application limit. Optional, per voice application. LeadRefinery does not use it.

The account today (checked 19 October 2026): the limit is 20, and it is the account limit. No voice profile and no voice application has its own limit; only the demo line has a limit of 4. Production, staging, the demo line and local tests share the 20. One dial takes approximately 35 seconds (s). Thus, over an 8-hour day, 20 open calls give approximately 16,000 dials a day for the full account.

An example size: 25,000 dials over an 8-hour day, each dial 30–40 s, is approximately 30–35 calls at the same time for 1 client. Several clients of that size need an account limit of approximately 100. Send the use case to Telnyx support and ask for this limit before a large client starts. After Telnyx raises the limit, give the voice profile of each client its own limit. Then 1 client cannot take the full account. The campaign limits decide how many dials a client makes each day.

Archive and delete

• Archive a client: the platform sets the client's voice application to inactive. Then nothing can dial through it. Restore sets the voice application to active again. The phone numbers stay with the client.
• Delete a client: the platform frees the phone numbers (environment tag only, no billing group). Then the platform deletes the voice application, then the voice profile, then the billing group. The phone numbers stay in the account. If Telnyx refuses a step, the platform refuses the delete and shows the reason.

How to read the invoice

In the Telnyx portal, open Mission Control → Reporting → Usage Reports. Group the report by Billing group. You get 1 row per client with rent and minutes. The detail reports (call records) can also filter by billing group.

Check the first invoice after a client gets its objects:

• The client's minutes must sit under the client's billing group.
• The rule "minutes follow the voice profile" comes from the Telnyx help pages, not from its developer reference.
• If the minutes sit under the billing group of the phone number instead, the split still holds. Tell engineering, so that engineering corrects the decision record.
• A row with "no billing group" is LeadRefinery's own cost: the demo clients and the test clients.

Clients created before the change

Clients created before 19 October 2026 have no objects. Do these steps for each client:

1. Open Organizations → the client → the Dialling tab. Press Create Telnyx objects. The step also binds every phone number already in the pool. The step skips retired phone numbers.
2. Save the tab. The picker already shows the new voice application.
3. Check 1 of the phone numbers in the Telnyx portal. Make sure that the phone number has the billing group and the client tag.

What is not built, on purpose

• No automatic purchase of phone numbers. You buy them by hand. A plan for a screen that sizes and buys phone numbers from the lead volume exists. LeadRefinery can build it later. What a lead costs shows the arithmetic that such a screen uses.
• No spend limit and no limit on calls at the same time on the client's voice profile. Each one is 1 field on the voice profile. LeadRefinery can add them later.
• No Telnyx cost inside the platform yet. The cost stored on each call is the figure from the voice service, as on What a call costs. You read the Telnyx split from the Telnyx invoice and the usage report.