Rate codes, rates, and tariffs

In PortaBilling, three key entities determine how service usage is billed:

• Rate codes define how a service is used – for example, the destination of a call (such as phone prefix 420 for Czech numbers) or the type of data that is accessed (such as text code RG101 for video streaming or RG102 web browsing).
• Rates define how much to charge for that usage. For example, you might charge $0.05 per minute for calls to Czech phone numbers.
• Tariffs are price lists made up of rates. Tariffs can be assigned to vendors (to calculate your costs), customers (to apply charges according to their product), and resellers.

Each time a customer uses a service (e.g., makes a call), PortaBilling identifies the rate code and looks up the applicable rate in the assigned tariff.

These three entities – rate codes, rates, and tariffs – are especially important for pay-as-you-go billing, where both your cost (to the vendor) and revenue (the customer’s charge) depend on usage. However, even when a service is included in a plan at no extra cost (e.g., as part of a bundle), a tariff is still required. PortaBilling uses it to:

• authorize service usage, and
• apply charges once the included allowance is used up.

The following sections explain each concept in detail.

Rate codes represent the phone number prefixes (e.g., the Czech prefix 420, which covers all phone numbers starting with 420) or other service identifiers. Each rate code corresponds to a specific area or usage type, such as a country, city, mobile network, or type of content accessed (e.g., video streaming). 

Rate codes can be defined in:

• E.164 format
• E.212 format
• Custom text format 

For voice calls, we recommend defining all phone number prefixes in the format <country code><area or mobile network code>, without the “+” at the beginning (e.g., 420603). PortaBilling also supports special codes, such as VOICEONNETRX, used for calls between extensions of the same cloud PBX customer.

You need to add a new rate code when introducing a new area or usage type that should be billed differently from others. All required rate codes must be added before they can be used in rates – this helps prevent errors and ensures data consistency.

You don’t need to maintain a full list of global prefixes – it’s nearly impossible to manage and doesn’t bring real benefits. Just add the rate codes you plan to use. PortaBilling supplies a file with a set of default codes, which you can download and then upload to the server during the initial configuration of PortaBilling. When uploading rates to tariffs, any new codes are added automatically.

If you are a mobile operator engaged in wholesale SMS delivery, you may need to define rate codes in the E.212 format. These consist of:

• MCC (Mobile Country Code) – e.g., 230 for the Czech Republic
• MNC (Mobile Network Code) – e.g., 03 for Vodafone

For service types other than those based on phone numbers, you may add text rate codes such as WIFI, NETACCESS (for internet access), or MOVIE-BLOCKBUSTER (for pay-per-view content). These work like regular rate codes in tariffs but use service-specific identifiers instead of number prefixes.

A rate defines how much to charge for a specific type of service usage, based on a given rate code (e.g., a phone number prefix or service identifier) and specific conditions (e.g., time of day, rounding, etc.).

To simplify routine rate updates, each rate in PortaBilling has an Effective from date – the exact time when the rate becomes active. This allows you to schedule rate changes in advance. For example, you can enter a new rate today that will take effect after midnight on January 1st.

When a rate is updated, PortaBilling doesn’t overwrite the old one. Instead, it creates a new entry with the updated values and a new effective date. This ensures that a complete history of all rate changes is stored.

To maintain a clear history of rate changes, rates that are no longer needed are not deleted from the system. Instead, they can be marked as discontinued. Discontinued rates are no longer used for rating but can be displayed in the web interface.

A tariff is a complete set of rates. It serves as a price sheet for billing service usage. 

You can use the following types of tariffs:

• Vendor tariffs – specify how much your vendor charges you. These are defined at the vendor connection level.
• Customer tariffs – specify how much you charge your customers. These are defined at the main product level (main products are assigned to customer accounts).
• Reseller tariffs – specify how much you charge your resellers. These are defined at the product level (for main products managed by resellers).

When a customer uses a service (e.g., makes a phone call to 420602555123), PortaBilling searches for matching rates (such as 420602 – $0.01/min) in both the vendor and customer tariffs. If the customer belongs to a reseller, PortaBilling also searches for a matching rate in the reseller tariff.

Since tariffs for voice calls are the most complex case, they will be the primary focus of this chapter.

To determine how much to charge for a service, PortaBilling generates a rate pattern – a string that identifies the event (such as a call) and helps locate the appropriate rate in the tariff.

In the simplest case, for a voice call, the rate pattern is just the called number. 

If a tariff includes multiple matching rate codes, PortaBilling always applies the longest matching rate code.

If the longest matching rate is marked as forbidden, PortaBilling does not fall back to a shorter, allowed rate and does not authorize the call. For example, if 420602 is the longest match and the 420602 rate is marked as forbidden, the call is not authorized. The 420 rate is not used as a fallback.

Rate patterns can also include keywords (text-based codes), which can be:

• Defined by PortaSwitch – e.g., VOICEONNET, which is automatically applied for outgoing on-net calls.
• Received from external systems – e.g., MOVIE_PREMIUM, used to charge for pay-per-view content.

For telephony events, the rate pattern may consist of:

• A text code (if applicable)
• The “pipe” (|) character as a separator
• The phone number

PortaBilling applies the following logic to determine the correct rate:

1. Check for a match by text code (e.g., VOICEONNET)
2. If no match is found, check by phone number (e.g., 42035). Typically, this is the destination number (CLD); however, in scenarios when it’s needed to charge based on the call origin, it can be the caller’s number (CLI).
3. If a match has still not been found, check for the fallback rate defined for the wildcard code (|). This is commonly used for incoming calls, where a flat $0.00 rate applies regardless of the number.

These are examples of rate patterns and corresponding rates found in the tariff for different scenarios:

If a customer attempts to use a service (e.g., dials a number) and there’s no matching rate code in their tariff:

• If outgoing calls are authorized via PortaBilling, the customer will not be allowed to call this destination.
• If a third-party gateway or switch allows the call without authorization, the customer will still be able to make the call, but PortaBilling won’t be able to bill it correctly, as no matching rate is found. In this case, an email alert is sent, and a special CDR is created in the database to record the call for review.

You can configure rounding precision (i.e., the number of decimal places) for each tariff to round up the charged amounts.

PortaBilling always rounds the charged amount upward in each individual xDR. For example, if rounding is set to two decimals, the values 1.204, 1.205, and 1.206 are all rounded up to 1.21.

To set the number of decimals:

Go to Tariff > General configuration, and choose the desired option in the Rounding precision field. The default value is 5 decimals.

Here’s a typical flow for setting up pricing in PortaBilling:

1. Define custom rate codes (for non-telephony services only)

   For services like internet access or pay-per-view video, define custom rate codes manually.

   For telephony services, this step is not needed – rate codes are created automatically when you upload rates to tariffs.
2. Create vendor tariffs
   • For telephony services, import your vendors’ price lists into their respective tariffs.
   • For non-telephony services, rates can be entered manually.
3. Create customer tariffs
   • For telephony services, upload customer-specific rates into the corresponding customer tariffs.
   • For non-telephony services, rates can be entered manually.
4. Assign tariffs
   • Assign vendor tariffs to vendor connections.
   • Assign customer tariffs to products.
5. Monitor changes
   • Schedule rate updates using effective dates to automate future pricing changes.