You have the flexibility to replace or remove the bundle assigned to an account or a customer at any time. This applies whether the bundle is assigned directly or via a main/add-on product.
A bundle can be changed or removed manually by an admin or via the API. Customers can change their bundles using external portals such as the Cloud PBX Self-Care Portal offered by PortaOne in the Add-on Mart.
When you change the bundle for a user by changing the add-on product assigned to the account, you can:
- Schedule when the new add-on product will be activated. PortaBilling will replace the active add-on product with the new one on the stated date.
- Replace the already active add-on product immediately. PortaBilling applies the bundle that’s defined in the new add-on product at once.
In this chapter, we’ll dive into the specifics of bundle changes for these bundle types:
Changing the “Balance-dependent renewable” bundles
While changing the Balance-dependent renewable bundle, note that:
- When bundle A is replaced with bundle B in a product, any unused service volumes from bundle A will roll over to bundle B if the rollover feature is enabled in bundle A.
- When an add-on product containing the bundle is unassigned, the fee that has already been charged will not be refunded.
Changing the “One-off with top-ups” bundles
When the One-off with top-ups bundle is replaced by another bundle of the same type and priority, any unused service volumes from the old bundle can be added to the new bundle's service volume, if the items in both bundles meet the following conditions:
- Identical code group that belongs to the same code group set (e.g., both bundle items in both bundles are associated with the US & Canada code group from the North America code group set).
- Identical service (e.g., for both bundle items provide voice call minutes).
- Identical threshold type (e.g., the provided service volumes are based on the service used).
Changing the “Renewable by calendar” bundles
When the Renewable by calendar bundle is replaced by another bundle of the same type and priority, any unused service volumes from the old bundle can be added to the new bundle's service volume, if the items in both bundles meet the following conditions:
- Identical service (e.g., both bundle items provide voice call minutes).
- Identical code group that belongs to the same code group set, (e.g., both bundle items in both bundles are associated with the US & Canada code group from the North America code group set).
- Identical threshold type (e.g., the provided service volumes are based on the service used). Identical renewal periods (e.g., both service volumes are renewed monthly).
- The Prorate thresholds for first usage period option is set identically – either enabled or disabled for both (e.g., when a bundle is assigned in the middle of a billing period, both service volumes are recalculated based on the number of days left until the end of the current billing period).
If the "Prorate thresholds for the first usage period" option is enabled for both bundles, unused service volume from the old bundle will also be prorated. See the Prorated threshold section for details.
- The Rollover period of service volume is set identically (e.g., both service volumes can be rolled over twice).
The system can prorate the service volumes within the new bundle based on the hour it is updated for the customer:
If the bundle is changed during the last hour of a billing period
If the bundle is assigned or changed during the last hour of the current billing period (starting from 11:00 PM in the customer’s time zone), the new bundle is activated only at midnight. Customers can only use the remaining service volume of the previous bundle until midnight, after which they start using the new bundle. In this scenario, prorating for both the previous and new bundles will not happen.
If the bundle is changed at any other hour of a billing period
When a user switches to a new bundle before 11:00 PM on the last day of a billing period, the new bundle is activated immediately. The service volume in the previous bundle is prorated based on the elapsed days of the billing period, excluding the day of bundle change. Meanwhile, the service volume in the new bundle is prorated according to the number of days remaining in the first usage period, including the day of the bundle change.
If the bundle is changed but prorating conditions are not met
If you change the prorated bundles but the conditions are not met, the user receives the prorated service volume only from the newly assigned bundle.
Bundle change when proration is disabled (the time of change does not matter)
| Scenario | Old bundle | New bundle | After the bundle change |
| Changing to a bundle with a bigger service volume | 60 minutes of calls, 50 is already used | 500 minutes of calls | John has 510 minutes in total, where 10 minutes are left from the old bundle and 500 are from the new bundle. |
| Changing to a bundle with a smaller service volume | 10 GB of internet, 8GB is already used | 7 GB of internet | Unable to browse the internet for the rest of the month because John has already used up all his new bundle (8 out of 7 GB). Starting next month, John will only have 7 GB of Internet traffic available. |
Bundle change when proration is enabled (the time of change matters)
| Scenario | Old bundle | New bundle | After the bundle change |
| Bundle change during the last hour of a billing period, e.g., 11:15 PM on the last day | 60 minutes of calls, 50 is already used | 100 minutes | Only 10 minutes (60-50=10) are available from the current bundle till midnight. Starting at midnight, John starts using the new bundle with 100 minutes (no prorating). |
| Bundle change at any other hour of the billing period, e.g., 6:00 PM on the last day | 60 minutes of calls, 50 is already used | 100 minutes | John has a total of 61 minutes available for the rest of the month, where 58 minutes (60*29/30=58) comes from the previous bundle and 3 minutes of calls (100*1/30=3) comes from the new bundle.
Next month, John starts using the new bundle with 100 minutes. |
| Bundle change but the proration conditions are not met | 100 minutes per month of calls to the USA, 59 minutes are already used | 200 minutes of calls to the USA and Canada | Only 107 minutes (200*16/30=107) of calls to the USA and Canada are available from the new bundle for the rest of the month. Since the new bundle provides calls to a new code group (USA&Canada), no unused minutes are carried over to the new bundle. |
Bundle change using the API
To change a bundle using the PortaBilling API, use the following methods:
- To change bundles included in the main product for a specific account, use the i_product parameter in the Update_account method.
- To change bundles associated with add-on products for the account, use the assigned_addons structure in the Update_account method. When using this method, the assigned_addons structure must contain the complete list of add-on products applicable to an account (i.e., the add-on products that will not be changed plus new add-on products that must be assigned to an account).
- If you need to change bundles assigned directly to a specific account, use the i_vd_plan parameter in the Update_account method.
- To change bundles assigned to a specific customer, use the i_vd_plan parameter in the Update_customer method.
- To change bundles included in any product, use the i_vd_plan parameter in the Update_product method.
