Enabling product self-activation by a customer

Service providers can enable their customers to assign more products on their self-care portals (built in-house or by a third party) using the PortaBilling API. For example, when a PBX customer wants to add new phone lines for new employees or activate additional features such as call recording, they can do this via the self-care portal without contacting a service provider.

Service providers can control which products to show to a specific customer and how many instances of a specific product can be activated in total via a customer agreement. It includes the list of main and add-on products that the customer can use and the allowed number of assigned (used) instances for each product.

There are two options for adding new accounts under a customer via PortaBilling API:

1. Adding new extensions (phone lines) by PBX customers while the corresponding accounts are generated automatically in PortaBilling. This feature is suitable for cloud PBX service and is already available on our Cloud PBX self-care portal, and service providers can also use it on their third-party or in-house developed self-care portals.
2. Creating new accounts, suitable for generic products. If a service provider builds a self-care portal for services other than cloud PBX, they can use this feature. For example, it is used on the IoT&M2M portal, where a user can add new SIM cards (accounts).
   Currently, accounts are always created in an inactive state so that they can be checked and then activated later on by an administrator or an external application.

Note that service providers can also enable their customers to block/unblock a specific account (if the account is blocked by PortaBilling administrator, the customer cannot manage it). For example, a company occasionally hires external marketing specialists for seasonal sales campaigns. When a campaign ends and a specialist leaves, the company blocks their extension (the service provider doesn’t charge a subscription fee for the days when an account is blocked). They unblock it when a specialist starts working again.

Customer agreement defines the set of main and add-on products that a specific customer can add to their service package via the service provider’s self-care portal (developed in-house or by a third party). To open the customer agreement on the PortaBilling UI, go to Customer > Finances > Agreements.

For example, a service provider has various products with different pricing for retail and enterprise customers in the system. The agreement for a customer includes only the products tailored for this customer segment, so, on the self-care portal, the customer can see only the allowed products. This means that the customer won’t be able to assign any other product in the system that is not meant for them, e.g., a retail customer won’t have the possibility to assign an enterprise product to their accounts.

Also, customer agreements allow service providers to limit the number of accounts with a specific product that a customer may have. These limits are configured according to the service provider’s business model. A service provider can offer packages that are activated per phone line, so a customer is charged for each package activation separately. Or a service provider can offer small businesses a service package that includes a bundle of the maximum allowed phone lines (along with additional features such as auto attendant) for a fixed price. In this case, a customer is charged a fixed price, no matter whether they activate the maximum allowed number of phone lines or less.

Let’s see how service packages corresponding to these two business models are configured and used:

1. “$6 each phone line”
   1. The administrator:
      1. creates a product that includes a $6 subscription;
      2. adds the product to the customer agreement with no limitation on the number of accounts that can use this product (optionally, the administrator can limit the number of accounts to protect the customer from “bill shock”).
   2. The customer:
      1. is allowed to assign this product to an unlimited number of accounts;
      2. is charged $6 for each.
2. “Up to 10 Cloud PBX phone lines for $30”
   1. The administrator:
      1. creates a product without a subscription;
      2. assigns the $30 subscription to the customer directly;
      3. adds the product to the customer agreement and limits the number of accounts that can use this product to 10.
   2. The customer:
      1. is allowed to assign this product to a maximum of 10 accounts;
      2. is charged $30 when they sign up for this service package;
      3. is not charged additionally when they assign this product to an account.

Let’s say a service provider has a new PBX customer, ABC. ABC will manage their extensions via a service provider’s custom self-care portal.

To add the main and/or add-on products to a customer agreement, the PortaBilling administrator should perform the following steps:

1. open the Customer > Finances > Agreement > click Main products or Add-on products > Add > select the main or add-on product from the list;
2. in the Quantity field, specify the number of accounts each product can be assigned to.
   NOTE: 0 (zero) means that the product can be assigned to an unlimited number of accounts.

Example 1.

The service provider offers ABC the following products: “Auto attendant $6 per line”, “Cloud PBX $10 per line”, and “Call recording $4 per line” (add-on product). Each product includes the corresponding subscription ($5, $6, and so on).

The customer agreement includes these products with the Quantity option set to 0 (zero) since these products can be assigned to an unlimited number of extensions.

Example 2.

The service provider offers ABC the cloud PBX package that includes 5 phone lines and 1 call recording add-on for $20 per month (charged via a subscription assigned to the customer directly).

The customer agreement includes the main product “Cloud PBX up to 5 phone lines” and the add-on product “Call recording”. The number of extensions is limited via the Quantity option to 5 and 1 extensions correspondingly.

The PortaBilling API method add_customer_extension allows PBX customers to create new extensions, while the corresponding accounts are generated automatically in PortaBilling. To ensure that accounts that are created automatically have unique IDs, the ID pattern of these accounts combines the internal customer ID and the extension number (if a customer creates an auto attendant, then the sequence number is used).

Let’s consider an example. Say ABC customer needs to create:

• the auto attendant and
• an extension for a new employee, John Doe

To create the auto attendant, the PBX customer opens their self-care portal (built by the service provider or by a third party), adds the auto attendant, and assigns the “Auto attendant” product to it. The account with a universal account role and corresponding assigned “Auto attendant” product is automatically generated in PortaBilling. The account ID will have the following format:

ph${i_customer}aa{num}, where:

• i_customer – internal ID of a customer record in PortaBilling;
• num – a sequence number of an auto attendant, created by the customer.

So, the account with the “Auto attendant” product created for the customer with i_customer= 46170 in PortaBilling has an ID ph46170aa1.

As soon as the PBX customer assigns a DID number 12094555948 to the auto attendant, this number is assigned as an alias to the ph46170aa1 account in PortaBilling.

Next, the PBX customer creates an extension for John Doe (e.g., 4665) and assigns the “Cloud PBX” product to it. The account with a universal account role and corresponding assigned product is automatically generated in PortaBilling. The account ID will have the following format:

ph${i_customer}x${extension_id}, where:

• i_customer – internal ID of a customer record in PortaBilling;
• extension_id – the number of the extension, created by the customer on the self-care portal.

So, the account (corresponding to the extension created on the self-care portal) for the customer with i_customer= 46170 is created in PortaBilling with the following ID: ph46170x4665.