DID provisioning and billing

Link copied to clipboard

DID inventory management

Link copied to clipboard

The DID inventory in PortaBilling facilitates working with the customer’s list of DID numbers, even if they are not currently assigned to any accounts. It also allows customers to manage their DID lists via the self-care interface.

Customers can see a list of currently provisioned numbers (and which extensions they are assigned to) on the “DIDs” tab of the customer self-care interface.

This approach can be used for geo and non-geo DIDs as well as for toll-free and premium numbers.

When working with DID inventory and provisioning DID numbers it is very important for service providers to have a clear idea of which costs they bear and which charges they apply to their customers.

DID number cost

Link copied to clipboard

DID providers traditionally offer DIDs on a “fixed monthly fee” basis, with no per-minute charges. The providers include access for obtaining “buying” rate information for a specific number via XML API (e.g., phone number 12065551234 will cost $5/month). This is the rate the DID provider will charge the ITSP that allocates the number to its network.

When you as the service provider obtain DID numbers from a DID provider, you are usually charged an activation fee and then monthly recurring costs for all of the DID numbers. Therefore, when provisioning DID numbers to your customers, you apply an additional markup to these charges in order to compensate for your costs and earn some profit. The parameters of the markup are defined in pricing batches.

Please note that activation costs do not increase the DID provider’s balance (a DID provider is provisioned as a vendor in PortaBilling). Monthly recurring costs are recalculated according to the vendor’s billing period and applied for all obtained DID numbers regardless of whether or not they are assigned to customers. These costs are what increase the vendor’s balance.

DID costs management

Link copied to clipboard

When your DID provider changes their pricing and sends you an updated DID list, all you have to do is upload it to the DID inventory.

To update the vendor costs in the DID inventory, select the Modify data of existing DIDs option during the DID upload. The new DID numbers from the .csv file, if any, will simply be uploaded to their respective vendor batches in the DID inventory.

DID numbers upload

Upon upload, the new vendor costs override previous costs for all DID numbers regardless of their status (Free, In Use, etc.). You will receive a notification stating the number of both new and updated DIDs that have been uploaded to the DID inventory.

DID fees (calculated as the sum of vendor costs and DID markup) are also modified automatically. Thus, customers using DID numbers are charged updated recurring fees. Their activation fees will not be recalculated.

Billing for DID number usage

Link copied to clipboard

Every DID number belongs to a pricing batch. The pricing parameters of this batch, if any, define which charges will be applied to a customer when a DID number is assigned to them.

This allows you to set up different pricing for different DID number provisioning (e.g., local or international ones).

Consider the following example:

A customer is assigned a US number with $5 in activation costs and $3 in recurring costs from the “Domestic numbers” pricing batch. The markup for this batch is defined as follows: a $1 additional activation fee and a $2 additional recurring fee. The customer is charged $6 ($5+$1) upon DID activation and a $5 ($3+$2) monthly recurring fee recalculated according to the customer’s billing period (i.e. if a customer has a semimonthly billing period, he is charged $2.5 per billing period).

Then the customer is assigned a Chinese DID number with $15 in activation costs and $5 in recurring costs from the “International numbers” pricing batch. This batch has the following DID markup defined: a $5 additional activation fee and $4 additional monthly recurring fee. The customer is now charged $20 ($15+$5) for DID activation and $9 ($5+$4) for the monthly recurring fee.

DID pricing parameters

Link copied to clipboard

DID pricing is defined by the following parameters:

  • Additional activation fee is a configurable fixed amount that is charged when a new number is provisioned, in addition to the DID provider’s activation fee.
  • Additional recurring fee is a configurable fixed amount that is always included in the recurring (monthly) charge.
  • Recurring fee markup is a configurable increase of the DID cost (charged by the DID provider) included in the recurring charge in addition to the actual DID cost. For instance, when defining the ability to dynamically assign US numbers from DIDWW, we can specify that we would like to include a 10% markup on the DID provider rates. Thus, if a customer assigns phone number 12065551234 (DIDWW rate $5/month), the end user will be charged $5.50/month. DID pricing parameters

As a result, the total charge for the DID would be:

  • At activation – DID provider activation charge + Additional activation fee.
  • Monthly – DID provider monthly charge + the markup, consisting of the Additional recurring fee and the Recurring fee markup. This formula is likely to result in some “inconvenient” numbers, such as 3.289, which are usually rounded up.


Link copied to clipboard

You can choose what rounding method to apply to the DID charges in the customer class.

You can select one of the following rounding methods:

  • Away from zero – this rounding method is selected by default. It works similar to rounding up but differs when rounding negative values. Positive and negative values round symmetrically. For example, if the rounding precision is set to two decimals, then:
    • 1.214, 1.215 and 1.216 all round up to 1.22.
    • - 1.214, - 1.215 and - 1.216 all round to - 1.22.
  • Half away from zero – this rounding method works similar to arithmetic rounding but differs when rounding negative values. Positive and negative values round symmetrically. For example, if the rounding precision is set to two decimals, then:
    • 1.214 rounds to 1.21, 1.215 and 1.216 all round to 1.22.
    • - 1.214 rounds to - 1.21, - 1.215 and - 1.216 all round to - 1.22.
  • Special rounding (malaysian) – formerly known as custom rounding. This type of rounding depends on the last decimal at precision point. For example, if the rounding precision is set to two decimals, then:
    • If the last decimal at precision point is [0...2], it is set to zero. For example, 1.204, 1.215 and 1.226 all round to 1.20.
    • If the last decimal at precision point is [3...7], it is set to 5. For example, 1.234, 1.255 and 1.276 all round to 1.25.
    • If the last decimal at precision point is [8...9], it is set to 0 and the previous decimal increases by 1. For example, 1.284, 1.296 all round to 1.30. Rounding method

Also, you can choose the number of decimals to round the DID charges in the Rounding precision option when creating a DID pricing batch.

Rounding precision

For instance, in a situation where number 12065551234 (which has a $1.00 activation fee and a $3.00 monthly fee charged by the DID provider) is provisioned by an end user, the DID pricing setup would be as follows:

  • $2.95 for additional activation fee,
  • $1 for additional recurring fee,
  • 10% for recurring fee markup,
  • and 0.01 (2 decimals) pattern for rounding precision. DID self-provisioning

If a customer has a shorter billing period, e.g., weekly, a proportion of the DID provider’s monthly fees will be used to calculate the customer’s charge.

Please keep in mind that if you are going to provisionally terminate a customer, this customer won’t be charged for any DID numbers assigned to them. At the same time, the DID provider will still charge you a fee (e.g., $5/month) because these DID numbers remain allocated to your network until the customer is permanently terminated.

Completely free of charge DID numbers

Link copied to clipboard

When you provide virtual DID numbers for internal use (e.g., for SIP calls among accounts within your network), you still want to see which of them are in use and which are available. The best way to do this is by using the DID inventory. However, since these DIDs are virtual, they are, as a rule, provisioned free of charge and incur no charges to customers.

Therefore, to manage such internal DID numbers differently the concept of completely free of charge DID has been introduced. These are the DID numbers that have no costs or charges associated with them and are therefore free of charge for every entity they are provisioned to.

When an administrator assigns a completely free DID number to a pricing batch and then provisions the DID number to a customer, no charges apply.

Since there are no recurring costs associated with the DID number, the vendor is not billed either. Thus, both customer and vendor balances remain unchanged since no xDRs are created in the database.

Consider the following example:

You operate with thousands of end users. The services you provide allow end users to make and receive calls within your network. Since end users are not available from outside of your network, they do not require geographic DID numbers. However, to identify them within your network, you provision them virtual DID numbers. For this, you use the pool of virtual DID numbers 87899800000-87899989999.

Since these are your own internal numbers, you bear no costs and apply no charges to customers for their usage. Therefore you have them as completely free of charge in the DID inventory.

When a customer signs up for a product directly or via a reseller, no costs for DID provisioning apply to the customer.

Frozen DIDs and DID pool

Link copied to clipboard

It may be that you do not want to immediately provision DID numbers acquired from a DID provider (e.g., you plan to release a new product next month and therefore need to keep the DIDs until then). In this case you need to prevent the DID numbers from being used by your customers and resellers.

In order to keep the DIDs unavailable for usage, they are uploaded to the DID inventory under the Frozen status. When frozen, DIDs are displayed on the administrator’s DID inventory page only.

Frozen DIDs

To allow resellers to provision DID numbers, the administrator simply releases them to the pool of available DIDs.

Release DIDs to the pool

The DID pool is the tool that allows you to control the DID numbers that will be provisioned by your resellers. It contains the numbers that are:

  • not frozen;
  • not assigned to pricing batches; and
  • not used as an account ID, account alias, or an access number.
In order to retrieve DID numbers from the pool, resellers must have pricing batches with a DID markup assigned to them, since this markup is what they are charged for DID number usage.

Consider the following example:

You are releasing a new product in two weeks – the cloud PBX solution for your corporate customers. For this you have acquired the following range of DID numbers: 12045556500 – 12045556599. You must be sure that these DID numbers remain reserved for provisioning until the product is released. Therefore you keep them frozen in the DID inventory.

When the product is released, you unfreeze the DID numbers by releasing them to the DID pool and then distribute them to respective pricing batches.

Or, if you want your resellers to provision DIDs along with the new product, leave some of these DIDs in the DID pool.

Assigning DID numbers to pricing batches

Link copied to clipboard

You can provision DID numbers to your customers either with your markup or free of charge. The type of pricing batch a DID number is assigned to is what determines whether it is free or not. The pricing batch type is selected during batch creation.

Pricing batch

To properly manage DID numbers and control your costs and revenue, it is important to assign each DID number to an appropriate pricing batch prior to allocating this number to a customer.

Assign the pricing batch

When a DID number is assigned to a customer from a pricing batch with a DID markup, the markup is applied to the customer.

Pricing batches reflect a DID markup specific for either an administrator or a reseller. An administrator does not see any pricing batches created by resellers because those contain resellers’ markups.

DID numbers assigned to a customer

When added to a free pricing batch, a DID number becomes free of charge. This means that no charges apply to either a customer or a reseller when a DID number from a free pricing batch is assigned to them (e.g., DID number 16045552879 has a $10 activation cost associated with it and is assigned to the free pricing batch. Customer John Doe signs up for the EasyCall product and is provided with the number 16045552879. He is charged nothing for the DID number activation yet the administrator now owes $10 to the DID provider).

You can move DIDs from the pricing batches they are currently assigned to to other pricing batches. If a DID number is not in use, it can be reassigned to any pricing batch, regardless of whether it is free or has a DID markup. However, if a DID number is allocated to a customer or a reseller, it can only be reassigned to the same type of pricing batch (i.e. to free pricing batches or to pricing batches with DID markup).

Individual pricing for DID numbers

Link copied to clipboard

Your customers may ask for a personal price when purchasing a DID number. Instead of creating a special pricing batch with this new markup and moving the DID numbers to it, now modify the existing one per DID. When you create an account, click the DID button, choose a particular DID number and specify the individual pricing for it.

Specify the individual price

A DID number with modified fees is automatically marked as having Individual pricing.

DID groups

Link copied to clipboard

To easily manage a large number of DIDs, administrators may use DID groups – a tool that allows arranging DID numbers into categories (for example, by geographic location).

Consider the following example. The service provider wants to distribute a group of North American DID numbers free of charge, a group of Canadian and Western European DID numbers at $3 per month, and a group of DID numbers from other countries at a 20% markup.

For this scenario, an administrator creates three DID groups and distributes the DID numbers among them. The administrator then creates three pricing batches with different pricing schemes and assigns the corresponding pricing batch to each DID group. The DID numbers are now ready to be distributed to customers.

Note that separating DID numbers into groups is an optional step which is solely intended to make DID number management more flexible and convenient.

DID provisioning to customers

Link copied to clipboard

Depending upon your business model, you can provision DIDs to your customers so that:

  • a customer is charged the same price for using different DID numbers ($5 monthly for US and UK DID numbers). This is defined by the pricing parameters of the pricing batch directly assigned to the customer;
  • a customer is charged different prices for using different DID numbers (e.g., $5 monthly for the US DID and $8 monthly for the UK DID number). This is defined by the pricing parameters of the pricing batch that a particular DID belongs to.

Additionally, you can define whether customers will be charged as soon as the DID numbers are assigned to them (and not yet provisioned as customer accounts) or only after the DID numbers have been provisioned to the customers as accounts or account aliases.

When provisioning a DID number from a pricing batch to a customer and if this customer has another pricing batch specifically assigned to him, the charges defined in the customer’s pricing batch will be ignored. Instead, the charges defined in the pricing batch that a DID number belongs to will apply.

If customers provision DID numbers from external vendors (i.e. by using on-demand DID provisioning), it is required that the pricing batch having the DID markup be assigned to them because they are billed according to the pricing parameters defined in this specific pricing batch.

A DID number explicitly assigned to a customer and used as an account or account alias is released from this customer once the alias or the account is terminated or changed. Although it remains within the respective pricing batch, it has free status within the DID inventory and is available for further provisioning.

Customers can keep the DIDs assigned to them (e.g., to create other aliases). To make this happen, a customer clicks Edit and unassigns the DID from the alias. This helps you fulfill your contractual obligations if customers have purchased DIDs for the long term.

However, if the customer is terminated, the DID number is released from the customer and has free status within the DID inventory.

Please refer to the DID Provisioning section of the Unified PortaSwitch Handbook Collection for detailed instructions of ways to provision DID numbers to customers.

DID number self-provisioning

Link copied to clipboard

Customers can self-provision the service provider’s DID numbers. For customers’ convenience, DID numbers are grouped by country and country area.

Consider the following example:

The service provider purchased a set of DID numbers and wants them to be made available to their customers with minimal administrative assistance.

An administrator defines the DID markups in pricing batches and distributes the DIDs to them.

If a customer needs some DID numbers for their business, they log in to the customer self-care interface and allocate some of the available DID numbers. The customer is then charged the price specified for the selected DIDs.

If the customer decides that they no longer need the DID number, they simply delete it from their list of allocated DIDs, the number is released from this customer and the customer is no longer charged for the use of it. The DID number can now be provisioned by other customers.

DID assignment

Note that when the customer deletes a provisioned DID number, the pricing batch it previously belonged to is preserved. So the DID number returns to the DID inventory and is once again available for all customers (regardless of whether or not they are allowed to provision DID numbers themselves).

If prior to deletion, the DID number was assigned to an account as an alias, this alias is removed in PortaBilling.

This allows customers to provision DID numbers by themselves, without administrative assistance, thus decreasing an administrator’s workload.

Reseller DID provisioning

Link copied to clipboard

Access to the DID pool allows resellers to use as many DID numbers as they need and then provision these numbers to their customers. This expands the service provider’s DID provisioning network and boosts sales.

To access the DID pool, resellers must have pricing batches assigned to them.

Subresellers access the DID pool only if they and their top-level resellers have pricing batches assigned to them.

Then, they can perform the following actions when provisioning DID numbers via the DID inventory.

These actions include:

  • Definition of the pricing strategy for DID number provisioning;
  • Distribution of DIDs retrieved from the DID pool to pricing batches with respective DID markups;
  • Assigning DID numbers to subcustomers;
  • Releasing DID numbers to the DID pool. Reseller DID Provisioning

The DID pricing strategy definition

Link copied to clipboard

As a preparatory step, a reseller defines the revenue he wants to receive as the DID markup after provisioning this or that DID number within a pricing batch. To associate a DID markup with a DID number, add the number to the corresponding pricing batch.

Another pricing strategy is to define the same DID markup for any type of DID number provisioned to the same customer (e.g., 10% to be added to the DID recurring cost). This is done by assigning a default pricing batch to a customer. Then, after a DID number is provisioned to the customer, add it to their pricing batch and the defined DID markup will be applied. Such a model is frequently used when DID costs are at first unknown (on-demand DID provisioning).

Retrieval of DID numbers from the DID pool

Link copied to clipboard

To manage DID numbers, a reseller retrieves them from the DID pool by assigning them to respective pricing batches. Once a DID number is retrieved from the DID pool, it is owned by the reseller and is therefore unavailable for provisioning by other resellers. Though the DIDs may not yet be provisioned to customers, charges for them are already applied to their owners: the resellers.

If a top-level reseller exceeds their credit limit, their subreseller will not be able to retrieve a DID number from the DID pool.

DID provisioning to customers

Link copied to clipboard

When a DID number is provisioned to a subcustomer, the charges are calculated for each party involved and are distributed as follows:

  • A top-level reseller is charged a DID number cost plus additional fees defined in the pricing batch assigned to this reseller;
  • A subreseller is charged the top-level reseller’s costs plus additional fees as defined in the pricing batch assigned to this subreseller;
  • A subcustomer is charged the subreseller’s costs plus the DID markup as defined by the subreseller in the pricing batch associated with this number.

Release of DID numbers to the DID pool

Link copied to clipboard

Any DID number managed by a reseller can be released by this reseller back to the DID pool if the DID number is not used as an account ID, account alias, or an access number. To do this a reseller must select the Release DIDs to the pool option and click Apply. While in the DID pool, the DID number is again visible to all other resellers and is available for provisioning.

Please note that if a reseller un-assigns a DID number from a pricing batch in the DID inventory, this number is not released to the DID pool. The reseller still owns this number and still bears the charges for its usage.

A reseller can provision a DID number to a customer either from a pricing batch or via a pricing batch that’s specifically assigned to this customer.

Thus, when a reseller deletes the alias or changes the account/alias ID, the assigned DID number is released as follows:
  • In case a DID number is provisioned to a customer from a pricing batch, it is released back to this pricing batch. This means that the reseller continues to bear the charges for this DID, though the customer is no longer charged for it.
  • In case a DID number is provisioned to a customer via a pricing batch specifically assigned to this customer, a DID number is automatically released to the pool. This means neither the reseller nor the customer owns this DID number and therefore no charges apply for the DID usage.

The reseller does not receive any notification about a DID release when they manage accounts or aliases.

The flexibility of DID provisioning for resellers reduces the load on your administrators and boosts sales.

On-demand DID provisioning and billing

Link copied to clipboard

While the traditional DID provisioning method is still used when an ITSP obtains a large pool of phone numbers and then one by one, assigns numbers from it to individual customers, the appearance of “whole world a-la carte” providers such as Voxbone, DIDWW or DIDX has changed the preferred way of delivering extra DID numbers from foreign countries as a value-added service. It is impractical to purchase blocks of numbers from every single country in the world in the hope that some customer is going to buy them. DID providers usually charge a monthly fee for each allocated number, so this mode will quickly become hard to sustain financially.

On-demand DID provisioning enables the end user to browse the complete inventory of DID or toll-free numbers available on the DID vendor side, online. When he picks a number, the sign-up process on the PortaBilling side will reserve and allocate that number on the DID provider side and provision it inside of PortaBilling (e.g., as an alias to an existing account). When the customer decides that he no longer needs the number (or changes the number to something else), the reverse procedure will happen – the number will be released on the DID provider side and the account/alias will be removed in PortaBilling. This gives you the ability to offer a wide variety of different DID numbers to the end user and only be charged by the DID provider for numbers actually used by customers.

On-demand DID provisioning

Interconnection with DID providers

Link copied to clipboard

All major DID vendors offer some type of API that can be used to query, reserve and release DID numbers. As APIs are different for different DID providers, a system of plug-in modules has been implemented (similar to those used for payment systems) that will easily allow the addition of new providers in the future.

The initial version of the DID provisioning module includes integration with DIDWW ( and DIDX ( providers – and more providers will be added soon based on requests from our customers.

Combined DID provisioning

Link copied to clipboard

To generate additional revenue you can grant customers with on-demand DID provisioning access both to your DID number pool and that of other external DID providers (DIDWW, DIDX, etc.).

Consider the following example:

EasyCall has a pool of DID numbers for Canada. The service provider SmartNet (with whom EasyCall exchanges DID numbers) owns DID numbers for the New York area.

EasyCall enables on-demand DID provisioning for their customer John Doe. So now John is able to self-provision Canadian and New York DIDs via his customer self-care interface.

To enable this functionality, the administrator adds the [DID]MixedSources=1 option for the WebCustom group on the Configuration server.

DID exchange among service providers

Link copied to clipboard

To grow the DID provisioning network, you can now grant access to your DID inventory to other ITSPs – DID buyers – via the API, and allow them to provision DID numbers from you on-demand. This enables you to become an active player at the wholesale DID market.

This is how it works:

On-demand DID provisioning for DID buyers is done via the DID provisioning interface, using the API. You configure the DIDPool server – client communication on the Configuration server, and then define the access to your DID inventory using the credentials of your DID provisioning customer. This customer will accumulate charges for all DID numbers provisioned from your system, therefore they must have the DID pricing batch assigned.

Your DID buyers consequently define you as their external DID vendor and thereby configure on-demand DID provisioning in their systems. Thus, your PortaSwitch operates as the DIDPool server while their systems function as DIDPool clients.

Of course, the routing among your systems must also be configured.

As before, the DID management itself is done within the DID inventory. When your DID buyer’s customer provisions a number from the DID pool, the following occurs:

  • The DID number in the DIDPool server system is assigned to your DID provisioning customer and acquires In Use status within the DID inventory.
  • The DID number appears in the DIDPool client system as being assigned to that customer.

The charges for DID provisioning and usage are calculated in both the DIDPool server and DIDPool client systems as follows:

  • The DID provisioning customer in the DIDPool server system is charged according to the DID pricing batch assigned to them.
  • The customer in the DIDPool client system is charged for DID number usage according to the markup defined in their DID pricing batch.
  • If a DID number is no longer required, it is released from the customer and returned back to your DID pool.

Consider the following example:

The service provider, EasyCall, owns a pool of 10 million DID numbers. SmartNet is another service provider who exchanges voice traffic with EasyCall. SmartNet wants to introduce residential VoIP services to their system and thus requires DID numbers.

EasyCall allows SmartNet to provision DIDs from them via their customer DID Distribution. To do this, EasyCall provides SmartNet with DID Distribution’s credentials.

SmartNet sets up DID provisioning in their system and provisions DID Distribution as the external DID provider. Now they can allocate DID numbers from EasyCall like they can from any other external provider.

When SmartNet no longer needs DID numbers and releases them to the DID pool, the numbers are returned to the EasyCall DID pool with the Free (not in use) status.

Thus, the ability to distribute DID numbers to other service providers and charge for their usage extends your clientele and provides vast opportunities for wholesale DID trade.

On this page

What's new
Admin manuals
UI help
Back to main menu