Rate code matching in bundles

Each bundle consists of one or more bundle items, where each of them:

• Specifies which service (e.g., Voice calls) and which specific code group, such as “Europe” or “Latin America” it applies to. The content (list of specific phone prefixes such as 420 for Czechia) of a code group is defined in a code group set, and the bundle is linked to it.
• Provides the service volume information, such as the number of free minutes per month, etc.

When a user (with an assigned bundle) makes a voice call, sends an SMS, or starts an internet session, the important question is which specific bundle item will be used (or whether it will be used at all). There are two main methods that PortaBilling can apply to determine which bundle item is applicable:

• Comparing the rate code (earlier selected for “pay as you go” rating in the tariff) with rate codes in the code group for the bundle item, or
• Using the so-called “rate pattern” (the full original phone number used by the customer, combined with any applicable special rate codes such as VOICEONNET for calls between VoIP users).

  

1. The admin selects a code group for each bundle item.
2. PortaBilling can search for the matching rate code in the bundle items using either the rate earlier selected in the tariff or the rate pattern.
3. If the matching rate code is found, the corresponding bundle item applies.

Sounds complicated, right? Let’s examine specific scenarios.

To define the method that PortaBilling will use to determine which bundle item is applicable, you need to select a rate lookup type for a bundle. The default lookup type is Matches the rate exactly.

With the Matches the rate exactly lookup type, a bundle item applies only if the code group associated with this bundle item contains exactly the same rate code as the one picked in the tariff for rating.

If a bundle has several applicable bundle items (e.g., it includes two bundle items, “Czechia” and “Czechia – mobiles”, the rate code 420602 was placed in both, and the customer calls 420602555123), the charging engine uses one of the bundle items randomly and ignores the others. This may produce unexpected results, e.g., PortaBilling may choose the bundle item that is already used up and ignore the available bundle item. It is best to avoid such ambiguity – for example, if within our product we plan to offer 500 minutes of calls to landlines in Czechia and 100 minutes to mobiles, the correct way is to set up bundle items for “Czechia landlines” and “Czechia – mobiles” code groups with a non-overlapping set of rate codes in each.

There are legitimate cases of having the same rate code in multiple groups within the same set – e.g., we plan to offer separate promotions (each defined as its own bundle) for calling Europe as well as the Spanish Speaking World, so Spain (phone prefix 34) has to be included in both. But when creating multiple bundle items within the same bundle – to be sure that a bundle item is applied as expected, avoid adding the same rate code to multiple code groups.

For special rate codes, the rate lookup works the same way – PortaBilling looks for the exact match to apply a bundle item. For example, a user makes an on-net phone call to 420602555888 (which is also a PortaSwitch account). The billing engine recognizes this as a special case, so it does a rate lookup for a special VOICEONNET rate code in the tariff. If a rate for such a rate code exists in the tariff (usually it does, since this is one of the main advantages of hosted PBX service) – then the bundle item applies only if the admin added the exact same rate code (VOICEONNET) to the corresponding code group “VoIP Calls between subscribers”.

A bundle item can apply to incoming and outgoing calls regardless of usage charges in product configuration (no matter whether a single tariff or distinct tariffs are configured for these calls). So, when you configure a bundle item, e.g., 100 minutes for calls to mobile numbers in Czechia, you need to be sure that it applies to outgoing calls only and that the minutes of incoming calls are not subtracted from the bundle item’s service volume.

With the Matches the rate exactly lookup type, you can ensure that the bundle item doesn’t apply to incoming calls by not including the rate codes used for incoming calls in the tariff in the code group associated with the bundle item.

The Matches or covers the rate option is outdated and available for backward compatibility only. We strongly recommend against using it when creating new bundles.

The rate code in the code group associated with the bundle item can be either equal to or more generic than the rate code in the tariff.

If PortaBilling finds a matching rate code (that is equal to or shorter than the rate code in the tariff) in more than one bundle item, the longest match is used.

Say, PortaBilling finds rate code 420 in the code group associated with bundle item A and rate code 420602 in the code group associated with bundle item B. In this case, the longest match (420602) is used, so bundle item B applies. And if PortaBilling finds the longest matching rate code (420602) in both bundle items – A and B, then a bundle item applies randomly (either A or B).

When this rate lookup type is selected for a bundle, PortaBilling doesn’t consider the rate code found in the pay-as-you-go tariff at all. PortaBilling performs the rate lookup based on the rate pattern.

This lookup type is useful, e.g., when you want to apply a bundle item based on a special rate code (keyword) and the pay-as-you-go tariff based on a CLD.

To check whether to apply the 100-minute bundle item for calls to favorite numbers, PortaBilling first searches for the special rate code FAV in the code group associated with the bundle item (since it’s the first part of the rate pattern “FAV|420602555123)”. As the admin added FAV to the code group used for the bundle item, PortaBilling matches it with FAV in the rate pattern, and the bundle item applies (since the first part of the rate pattern is found, the second part, 420602555123, is not used for the rate lookup). And when 100 minutes are used up, the call is charged as usual according to the 420602 rate in the pay-as-you-go tariff.

Let’s say, from the start of the next month, Panda Telecom stops offering the 100-minute bundle item for calls to favorite numbers. John Doe decides to subscribe to a new bundle with free minutes to Czechia instead. The new bundle is assigned to John’s account via the new add-on product. 420602555123 is still in John Doe’s “phone book” as his favorite number. Next month, John makes a call to 420602555123 (the rate pattern is “FAV|420602555123”). PortaBilling performs a rate lookup to find a bundle item to apply, and doesn’t find FAV in any code group in the new bundle. So, PortaBilling makes another search using the dialed number 420602555123.

Note that if John Doe calls a number that is not marked as favorite, e.g., 420602555456, the rate pattern for this call doesn’t contain a keyword: “420602555456”. In this case, PortaBilling makes a search using the dialed number 420602555456 right away. When rate lookup finds a code group that includes matching rate codes covering the CLD number, such as 420 or 420602, then the corresponding bundle item applies to the call.

If PortaBilling finds an equal or shorter rate code in more than one bundle item, the longest match is used. It works similarly to If matching rate codes are found in several code groups (for Matches or covers the rate lookup type), with the only difference being that here the rate lookup is based on the keyword/CLD from the rate pattern instead of the rate code from the tariff.

Use the Matches the rate pattern lookup type with caution, because a bundle item may apply to the incoming calls.

With Matches the rate pattern lookup type, the bundle items will also apply to the incoming calls if the CLD rate code is found in the code group associated with one of the bundle items. This is because this lookup type uses both parts of the rate pattern to search for a matching rate code.

This lookup type consumes the most system resources, since multiple searches in the code groups may be performed.