25 XML Examples of Creating Pricing Components
This chapter describes how to configure pricing components in Oracle Communications Billing and Revenue Manager (BRM) by using an XML file and the loadpricelist utility.
Topics in this document:
-
Aligning Recurring Charges and Product Validity to a Specific Day of the Month
-
Splitting Noncurrency Balances into Multiple Validity Periods
-
Defining Product Specification Attributes for Pricing Components
- Enabling Dynamic Credit Floors in Plans
The following topics show examples of creating pricing components using XML elements in your price list file.
Prorating Fees for Billing DOM Changes
When configuring rates in XML, you can specify how to apply cycle fees when customers change their billing day of the month (DOM) in the middle of their billing cycle. For example, on June 15, a customer changes his billing DOM from the 10th to the 30th, generating a partial month. You can specify whether the June 10 through June 30 bill contains the entire monthly cycle fee, a prorated monthly cycle fee, or no monthly cycle fee.
To do so, set proration_flag in the <rate> element to one of the following:
-
full: Applies the total cycle fees.
-
prorate: Prorates the cycle fees. This is the default.
-
none: Applies no cycle fees.
The following sample XML entries specify to prorate cycle fees when customers change their billing DOM during a billing cycle:
<rate type="default" proration_flag="prorate">
<description>$9.95 a month</description>
<step_resource_id>840</step_resource_id>
<quantity_tier>
<balance_impact scaled_unit="none" flag="sponsorable discountable proratable">
<resource_id>840</resource_id>
<glid>102</glid>
<fixed_amount>10.0</fixed_amount>
<scaled_amount>0</scaled_amount>
</balance_impact>
</quantity_tier>
</rate>Setting Proration for Products in a Deal
When configuring deals in XML, you can specify how each product in the deal calculates prorated cycle fees. For example, a deal could contain one product or discount that prorates based on 30-day months and another that is based on the actual number of days in the month.
To set proration at the product level in your deals, set flags in the <deal_product> element to one of the following:
-
prorate_30_day: Prorated cycle fees are calculated based on a 30-day month, regardless of the number of days in the billing cycle. For example, if a deal was owned for six days in a cycle, the prorated fee would be the cycle fee multiplied by 0.20 (6 ÷ 30).
-
prorate_days_in_month: Prorated cycle fees are calculated based on the number of days in a particular month, such as 28 days in February, 31 days in March, and 30 days in April. For example, if a deal was owned for six days in March, the prorated fee would be the cycle fee multiplied by 0.19 (6 ÷ 31).
-
prorate_system: Prorated cycle fees are calculated according to the system-wide setting in your CM pin.conf file. See "Enabling 30-Day-Based Proration" in BRM Configuring and Running Billing.
Note:
It is applicable only on products and does not affect discounts as discounts are always relative to products and therefore not subject to proration settings.The following sample XML entries create a deal named Sample Deal with products Product01 and Product02. Product01 specifies to prorate all of its cycle fees using a 30-day month, Product02 specifies to prorate all of its cycle fees based on the actual number of days in the month:
<deal customization_flag="optional" ondemand_billing="no">
<deal_name>Sample Deal</deal_name>
<description>My Sample Deal</description>
<permitted>/service/ip</permitted>
<deal_product flags="prorate_30_day">
<product_name>Product01</product_name>
<product_code>My Sample Product</product_code>
<quantity>1.0</quantity>
<purchase_discount>0.0</purchase_discount>
<cycle_discount>0.0</cycle_discount>
<usage_discount>0.0</usage_discount>
<purchase_mode>0</purchase_mode>
<deal_product flags="prorate_days_in_month">
<product_name>Product01</product_name>
<product_code>Another Sample Product</product_code>
<quantity>1.0</quantity>
<purchase_discount>0.0</purchase_discount>
<cycle_discount>0.0</cycle_discount>
<usage_discount>0.0</usage_discount>
<purchase_mode>0</purchase_mode>
</deal_product>
You can modify the flags value by using the PCM_OP_PRICE_SET_PRICE_LIST opcode. However, after customers subscribe to your deals, further updates to flags do not affect any purchased products.
You can override the flags value for a specific customer using the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL or PCM_OP_CUST_COMMIT_CUSTOMER opcode. See "Overriding Bundle Proration Settings at Customer Level" in BRM Opcode Guide for more information.
Setting Full Day Proration
To configure full day proration in XML, you use the <validityRounding> and <scaleRounding> elements.
<validityRounding> specifies whether to start the charge offer's validity period at the purchase time or midnight of the purchase day.
Set the <validityRounding> element to one of the following:
-
OFF: Starts at the time of purchase.
-
ON: Starts at midnight (00:00:00) of the day that the charge offer is purchased.
-
NOT_SET: Uses your company’s systemwide setting.
<scaleRounding> specifies how to calculate the scale.
-
ON: Calculate it based on full days.
-
OFF: Calculate it based on the <validityRounding> setting.
-
NOT_SET: Use the systemwide setting in the CM pin.conf file.
The following sample XML entries specify to start the validity period at midnight on the purchase day and charge for a full day on the first day of the billing cycle:
<?xml version="1.0" encoding="UTF-8"?>
<price_list version="7.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="price_list.xsd">
<product date_range_type="EVENT_DATE" partial="no" type="subscription">
<product_name>MCF - $30</product_name>
<product_code>MCF30</product_code>
<offer_validity_rounding>NOT_SET</offer_validity_rounding>
<scale_rounding>OFF</scale_rounding>
</price_list>Adding Pricing Tags to Rates
You can configure BRM to dynamically charge different one-time and recurring rates for the same event based on the date. For example, when a customer cancels a product, you could charge a default amount of $50, but charge $45 in June and $40 in July. To do so, you add a predefined pricing tag to the balance impacts in your price list XML file.
For more information about dynamic charging, see "Dynamically Changing One-Time and Recurring Fees Based On the Date".
To add pricing tags to rates, set the following elements under the <balance_impact> element:
-
<fixed_price_tag>: Set this to the price tag name for overriding a fixed amount.
-
<scaled_price_tag>: Set this to the price tag name for overriding a scaled amount.
The following sample XML entries add the PRICE1 pricing tag to fixed balance impacts, and the PRICE2 pricing tag to scaled balance impacts:
<?xml version="1.0" encoding="UTF-8"?>
<price_list xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="price_list.xsd" version="7.2">
<rate type="default" prorate_first="prorate" prorate_last="full" step_type="total_quantity_rated">
<description>$9.95 a month</description>
<step_resource_id>840</step_resource_id>
<quantity_tier>
<balance_impact scaled_unit="none" flag="sponsorable discountable proratable">
<resource_id>840</resource_id>
<glid>102</glid>
<fixed_amount>10.0</fixed_amount>
<fixed_price_tag>PRICE1</fixed_price_tag>
<scaled_amount>5.0</scaled_amount>
<scaled_price_tag>PRICE2</scaled_price_tag>
</balance_impact>
</quantity_tier>
</rate>
</price_list>In this example, BRM would charge:
-
A default fixed amount of $10. When the PRICE1 pricing tag matches a pricing tag and date range combination in the /offering_override_values object, BRM would charge the fixed amount defined in /offering_override_values.
-
A default scaled amount of 5%. When the PRICE2 pricing tag matches a pricing tag and date range combination in the /offering_override_values object, BRM would charge the scaled amount defined in /offering_override_values.
Allowing Customers to Exceed Their Credit Limit
When configuring rates in XML, you can specify what happens to subscriptions when customers exceed their credit limits.
To do so, set type in the <rate> element to one of the following:
- normal: Enforce the credit limit. The subscription succeeds, but customers stay within their credit limit. Prorate the subscription according to the available balance.
- default: The subscription succeeds, and all available balance is used. The remaining amount is tracked as a negative account balance to be paid at the next top up for prepaid customers or current bill for postpaid customers.
- loan: The subscription succeeds. If the customer is eligible
for a loan, all available balance is used and a loan is granted for the
remaining amount. If the customer is not eligible for a loan, the subscription
fails.
See "About Loans" in BRM Configuring and Collecting Payments for more information about loans.
- deduct_rental: The subscription succeeds, and all available balance is used. The remaining amount is recorded as an outstanding amount to be paid at the next top up for prepaid customers or the current bill for postpaid customers.
- outstanding_amount: The subscription succeeds without using the available balance. The entire amount is recorded as an outstanding amount to be paid at the next top up for prepaid customers or the current bill for postpaid customers.
- rental_failure: Enforce the credit limit. The subscription fails. After retrying the subscription the configured maximum number of times, a notification event is sent to an external system for further processing.
- auto_renew_cancel: Enforce the credit limit. The subscription fails. After retrying the subscription the configured maximum number of times, a notification event is sent to an external system for further processing, and the subscription is canceled. It will not automatically renew the next cycle.
- skip_cycle: The subscription succeeds without using the available balance. Services will still be available, but billing will be skipped for this cycle. During rating, all balance impacts are dropped, and the unrated quantity is set to 0. The cycle forward date is moved to the next cycle.
- minimum_amount: The subscription succeeds if the customer's
balance is at least a configured minimum amount. If they have enough balance for
the full amount, the full amount is charged. If they have less than the full
amount, but more than the minimum amount, the minimum amount is charged. If they
have less than the minimum amount, the subscription fails, and the behavior is
the same as for rental_failure.
For this option, you can also configure the following:
- The minimum amount in the <minimum_scaled_amount> element. By default, this is set to 0, which means the subscription fails if the balance is less than the total amount.
- Whether or not to prorate the service according to the minimum amount in the prorate_quantity flag of the <rate> element. By default, this is set to yes, and the service will be prorated. Set this to no to grant the full service for the minimum amount.
This option is helpful if you want to offer your customers a small amount of their service, such as a few MB of data or minutes as an emergency stop-gap until they have enough balance to afford the full service.
For the rental_failure, auto_renew_cancel, and minimum_amount options, you can also configure the following when defining the product:
- The maximum number of times to retry the subscription before it fails. Configure this in the <max_retry_count> element of the product. The default is 0, which sends the failure notification immediately without retrying.
- The frequency of subsequent retries. Configure this in the charge
offer's <retry_unit> and <retry_offset> elements. The
values for <retry_unit> are:
- 1: Seconds
- 2: Minutes
- 3: Hours
- 4: Days
- 5: Months
- 6: Years
- 10: Weeks
The default for <retry_unit> is 4 and <retry_offset> is 1.
The /purchased_product object stores the current number of retries for the subscription in the PIN_FLD_RETRY_COUNT field and the date and time of the next retry in the PIN_FLD_NEXT_RETRY_T field.
If you do not configure the retry parameters at the offer level, the value for the max_retry_count business parameter is used. By default, this is set to 0, which fails the subscription immediately without retrying. See "Configuring the Maximum Number of Subscription Retries" in PDC Creating Product Offerings for more information about setting this parameter.
The following XML rate and product example specifies to charge a minimum amount and prorate the service when customers exceed their credit limit. It also specifies to retry failed subscriptions a maximum of 3 times, every 6 hours.
<rate prorate_first="prorate" prorate_last="prorate" prorate_quantity="yes" step_type="total_quantity_rated" type="minimum_amount">
<description>Monthly Cycle Forward $12</description>
<step_resource_id>0</step_resource_id>
<quantity_tier>
<balance_impact flag="proratable" scaled_unit="none">
<resource_id>840</resource_id>
<glid>0</glid>
<fixed_amount>2.0</fixed_amount>
<scaled_amount>10.0</scaled_amount>
<minimum_scaled_amount>5.0</minimum_scaled_amount>
</balance_impact>
</quantity_tier>
</rate>
...
<product date_range_type="EVENT_DATE" partial="no" type="subscription">
<product_name>MCF - $30</product_name>
<product_code>MCF30</product_code>
<priority>0.0</priority>
<description>Monthly cycle forward charges.</description>
<permitted>/service/ip</permitted>
<max_retry_count>3</max_retry_count>
<retry_offset>6</retry_offset>
<retry_unit>3</retry_unit>
</product>You can also use the importexportpricing utility or the PCM_OP_PRICE_SET_PRICE_LIST opcode to update these values.
Transitioning Plans and Deals
When configuring plan or deal transitions in XML, you can specify how to apply charges when customers perform transitions in the middle of their billing cycle. To do so, set proration_flag under the <transition> element to one of the following:
-
force_prorate: Prorates charges for both plans or both deals. This is the default.
-
chg_full_from_svc: Applies the full charges for the original plan or deal, and applies no charges for the new deal or plan.
-
chg_full_to_svc: Refunds the charges for the original plan or deal, and applies the full charges for the new plan or deal.
The following sample XML configures BRM to prorate charges from both deals when your customers transition from one deal to another in the middle of their billing cycle:
<transition fee_flag="3" service_type="/service/ip" type="1" proration_flag="force_prorate">
<from type="/deal">Deal A</from>
<to type="/deal">deal_product_not_aligned_inadvance</to>
</transition> Configuring Add-On Products in Deals
When creating deals in XML, you can add base products and add-on products. All products in deals are base products by default, which means they can be purchased without any prerequisites. Add-on products require customers to own a valid base product.
You customize a product in a deal to be an add-on product by including the <validity_align_mode> element under <deal_product>. The add-on product's validity start date is the end date of a product that you specify. For example, assume product A has a validity period from June 1 through June 15. If you specify to align add-on product B's validity period with product A, product B's validity start date would be June 15.
You specify the product on which to align an add-on product's validity dates by setting the <validity_align_mode> element to one of the following:
-
base: Aligns the validity dates with the specified base product. If set to base, you must also include these elements:
-
<base_product_name> set to the name of the base charge offer on which to set validity dates.
-
<base_product_code> set to the code of the base charge offer on which to set validity dates.
-
-
any_base_earliest: Aligns the validity dates with the active base charge offer that expires first.
-
any_base_latest: Aligns the validity dates with the active base charge offer that expires last.
-
any_earliest: Aligns the validity dates with the active charge offer that expires first.
-
any_latest: Aligns the validity dates with the active charge offer that expires last.
The following sample XML entries create a deal that includes an add-on product with a validity date aligned with that of BASE_PRODUCT_SMS:
<deal customization_flag="optional" ondemand_billing="no">
<deal_name>Dealp1d1</deal_name>
<description>Dealp1d1</description>
<permitted>/service/ip</permitted>
<deal_product status="active">
<product_name>p1</product_name>
<product_code>p1</product_code>
<quantity>1.0</quantity>
<purchase_start unit="month">5</purchase_start>
<purchase_discount>0.0</purchase_discount>
<cycle_start unit="month">5</cycle_start>
<cycle_discount>0.0</cycle_discount>
<usage_start unit="month">5</usage_start>
<usage_discount>0.0</usage_discount>
<purchase_mode>0</purchase_mode>
<validity_align_mode>base</validity_align_mode>
<base_product_name>BASE_PRODUCT_SMS</base_product_name>
<base_product_code>abcd-kfhg-sdjd-fgjk</base_product_code>
</deal_product>
</deal>You can also create or modify a deal with add-on products by using the PCM_OP_PRICE_SET_PRICE_LIST opcode. However, after customers subscribe to your deals, further updates to the product have no effect on any purchased products.
You can override the add-on product's validity dates for a specific customer by using the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL or PCM_OP_CUST_COMMIT_CUSTOMER opcode. See "Overriding Add-On Product Validity Dates in a Bundle" in BRM Opcode Guide for more information.
Purchasing the Same Product or Discount Multiple Times
When creating deals in XML, you can specify what happens if customers purchase the same product or discount more than once. The additional product or discount can be purchased as a new subscription, as a replacement of the existing subscription, or as an extension of the existing subscription if the additional product is purchased within a specified grace period.
Set the value for the <purchase_mode> element under the <deal_product> or <deal_discount> element to one of the following:
-
0: The additional product or discount is purchased as a new, unrelated subscription. The balance impacts and validity periods of the old and new subscription are completely independent. This is the default option.
-
1: The additional product or discount is purchased as an extension to the existing subscription if it is purchased within the specified grace period. The new resources are added to the existing balance group. The validity period for the resource is then set to either the old validity end date or the new validity end date, whichever is later.
For example, on June 1, a customer purchases a deal that grants 3GB of data, is valid for 7 days, and has a grace period of 4 days. On June 3, after using 1GB, they purchase the deal again. The new 3GB balance is added to the remaining balance, for a total remaining balance of 5GB. BRM compares the validity periods of the old and new product and sets the validity end date for the total balance to the later of the two end dates, June 10.
-
2: The additional product or discount is purchased as an extension to the existing subscription if it is purchased within the specified grace period. The new resources are added to the existing balance group. The validity period for the resource is then set by adding the new validity period to whatever remains of the old validity period.
For example, on June 1, a customer purchases a deal that grants 3GB of data, is valid for 7 days, and has a grace period of 4 days. On June 3, after using 1GB, they purchase the deal again. The new 3GB balance is added to the remaining balance, for a total of 5GB. BRM adds the validity period of the new product to the old deal, and sets the validity end date for the total balance to June 15.
-
3: The additional product or discount replaces the existing subscription. The existing subscription is canceled, any configured proration is applied, and the new subscription is created, with all resources and validity periods set as though for a new purchase.
For example, on June 1, a customer purchases a deal that grants 3GB of data and is valid for 7 days. On June 3, after using 1GB, they purchase the deal again. The old subscription is canceled, any remaining balance is prorated, and the new 3GB balance is created, with a validity end date of June 10.
-
4: The additional product or discount is purchased as an extension to the existing subscription if it is purchased within the specified grace period. The new resources are added to a new balance group. The new balance's validity period starts on the purchase date, and ends either on the old validity end date or the new validity end date, whichever is later.
For example, on June 1, a customer purchases a deal that grants 3GB of data, is valid for 7 days, and has a grace period of 4 days. On June 3, after using 1GB, they purchase the deal again. The new 3GB balance is added to a new balance group, separate from the remaining 2GB in the old balance group.
The new balance is valid starting from June 3. BRM calculates the validity end date by comparing the validity periods of the old and new balances and setting the validity end date for the new balance to the later of the two end dates, June 10. The old balance retains the original validity dates.
-
5: The additional product or discount is purchased as an extension to the existing subscription if it is purchased within the specified grace period. The new resources are added to a new balance group. The new balance's validity period starts on the end date for the old balance's validity and the end is set by adding any remaining validity from the old balance to the total validity of the new balance.
For example, on June 1, a customer purchases a deal that grants 3GB of data, is valid for 7 days, and has a grace period of 4 days. On June 3, after using 1GB, they purchase the deal again. The new 3GB balance is added to a new balance group, separate from the remaining 2GB in the old balance group.
The new balance is valid starting June 8. BRM calculates the new balance's validity end date by adding the validity period of the new balance to what remains of the old balance, and setting the validity end date for the new balance to June 15. The old balance retains the original validity dates.
When you extend the existing product or discount by setting <purchase_mode> to 1. 2, 4, or 5, you can also include a grace period during which the additional product or discount must be purchased to qualify for the extension. To do so, set the following elements:
-
<grace_period_offset>: Set this to the amount of time in the grace period. The default is 0, which specifies a grace period that never ends.
-
<grace_period_unit>: Set this to the unit of the grace period: 0 (seconds), 1 (minutes), 2 (hours), or 3 (days). The default is 2 (days).
The following shows a sample of the XML for a product and a discount in a deal with purchase_mode set. The sample product specifies to extend the existing subscription and add the new and existing validity periods. The product is extended only if the additional product is purchased within two days of the existing product's expiration date.
The sample discount specifies to replace the existing discount with the new discount.
<deal customization_flag="optional" ondemand_billing="no">
<deal_name>IP Deal</deal_name>
<description>IP deal with purchase mode</description>
<permitted>/service/ip</permitted>
<deal_product status="active">
<product_name>Extending Product</product_name>
<product_code>ExtendingProduct</product_code>
<quantity>1.0</quantity>
<purchase_start unit="month">5</purchase_start>
<purchase_discount>0.0</purchase_discount>
<cycle_start unit="month">5</cycle_start>
<cycle_discount>0.0</cycle_discount>
<usage_start unit="month">5</usage_start>
<usage_discount>0.0</usage_discount>
<purchase_mode>2</purchase_mode>
<grace_period_offset>2</grace_period_offset>
<grace_period_unit>3</grace_period_unit>
<renewal_mode>1</renewal_mode>
</deal_product>
<deal_discount status="active">
<discount_name>Overwriting Discount</discount_name>
<discount_code>OverwritingDiscount</discount_code>
<quantity>1.0</quantity>
<purchase_mode>3</purchase_mode>
</deal_discount>
</deal>Aligning Recurring Charges and Product Validity to a Specific Day of the Month
When creating products in XML, you can use the calendar_dom and cycle_fee_flags fields to align recurring charges and product validity to a specific day of the month instead of the customer's billing date.
- To align recurring charges and product validity to a specific day of the month, set calendar_dom to an integer from 1-31 and set cycle_fee_flags to 1.
- To align recurring charges and product validity to the billing date, set calendar_dom to 0. The value of cycle_fee_flags is irrelevant in this scenario.
- To align recurring charges to the billing date but align product validity to a specific day of the month, set calendar_dom to an integer from 1-31 and set cycle_fee_flags to 0.
Caution:
You cannot change the calendar_dom value for a product after it has been purchased. If you create a new version of the product with a different value in calendar_dom, BRM does not update the value in any purchased products and continues to use the value that was configured for the initial purchase.For example, to align cycle rates and validity for a product to the 22nd day of the month, the XML input file would include the following:
<product type="subscription" partial="no" date_range_impact_type="INSTANTIATED_DATE">
<product_name>Product for a Specific Day of the Month</product_name>
<product_code>5fac608f-ba2b-4e83-adc3-7563e349158f</product_code>
<priority>1</priority>
<permitted>/service/telco/gsm/telephony</permitted>
<event_rating_map tod_mode="start_time" timezone_mode="event" min_unit="none" incr_unit="none" rounding_rule="nearest" flag="not_rate_cancelled">
<event_type>/event/billing/product/fee/cycle/cycle_forward_monthly</event_type>
<rum_name>Occurrence</rum_name>
<min_quantity>0</min_quantity>
<incr_quantity>1</incr_quantity>
<rate_plan_name>Rate Plan for a Specific Day of the Month</rate_plan_name>
<rate_plan_code>Occurrence-1bb17036-84ef-48be-9458-3b2922cf5276</rate_plan_code>
<rate_plan tax_when="never">
<rate_plan_name>Rate Plan for a Specific Day of the Month</rate_plan_name>
<rate_plan_code>Occurrence-1bb17036-84ef-48be-9458-3b2922cf5276</rate_plan_code>
<currency_id>840</currency_id>
<event_type>/event/billing/product/fee/cycle/cycle_forward_monthly</event_type>
<advance_billing_offset>0</advance_billing_offset>
<cycle_fee_flags>1</cycle_fee_flags>
<rate_tier date_range_type="absolute">
<rate_tier_name>RateTier_0</rate_tier_name>
<priority>100</priority>
<date_range relative_start_unit="none" relative_end_unit="none">
...
</date_range>
</rate_tier>
<rate_tier date_range_type="absolute">
<rate_tier_name>RateTier_1</rate_tier_name>
<priority>90</priority>
<date_range relative_start_unit="none" relative_end_unit="none">
...
</date_range>
</rate_tier>
</rate_plan>
</event_rating_map>
<calendar_dom>22</calendar_dom>
</product>If a customer with a billing date of the 14th of the month purchased the product in this example on January 18, their first cycle forward fee would be applied on January 18, prorated to cover the period between January 18 and January 22 (the calendar_dom date.) The next fee would be applied on January 22, at the full amount to cover the period between January 22 and February 22. Bills would be generated on the 14th of each month.
However, if the value of cycle_fee_flags in the example above was 0, the first cycle forward fee would be applied on January 18, prorated to cover the period between January 18 and February 14 (the billing date). The next fee would be applied on February 14, at the full amount to cover the period between February 14 and March 14. In the final month of the product's duration, it would only be valid until the 22nd of the month (the calendar_dom date.) If the product was valid for three months, the final fee would be prorated to cover the period from March 14 to March 22.
Note:
For products in deals that are suspended and then reactivated, you can specify that the cycle aligns with the reactivation date rather than the original purchase date using the renewal_mode element under the deal_product element. See "Setting Product Cycle Alignment for Reactivated Deals" for information about how renewal_mode interacts with calendar_dom and cycle_fee_flags.Splitting Noncurrency Balances into Multiple Validity Periods
When creating products in XML, you can grant noncurrency balances in smaller portions on an incremental basis. For example, you could grant 30 Gigabytes with a one-month validity that is distributed as 1 Gigabyte per day.
Set the <split_bucket> element under the <balance_impact> element as follows:
<split_bucket validity="validityType" unit="unit">amount</split_bucket>where:
-
validityType is either bucket (the balance expires at the end of the incremental validity period) or total (the balance expires at the end of the total validity period).
-
amount and unit specify the length of each incremental validity period, such as five hours or two days.
For example, to create an incremental validity period of four hours that has its noncurrency resources expire at the end of the total validity period:
<product>
<event_rating_map>
<rate_plan>
<rate_tier>
<rate>
<quantity_tier>
<balance_impact scaled_unit="none" flag="discountable grantable sponsorable">
<resource_id>100002</resource_id>
<impact_category>default</impact_category>
<glid>0</glid>
<fixed_amount>0.0</fixed_amount>
<scaled_amount>-233.0</scaled_amount>
<split_bucket validity="total" unit="hour">4</split_bucket>
</balance_impact>
</quantity_tier>
</rate>
</rate_tier>
</rate_plan>
</event_rating_map>
</product>Setting Product Cycle Alignment for Reactivated Deals
When creating deals in XML, you can specify when the cycle should align for products if a customer suspends and then reactivates the deal.
Set the value for the renewal_mode element under the deal_product element to 1 or 0. This setting is not valid for discounts.
If renewal_mode is set to 0, then the cycle aligns as described in "Aligning Recurring Charges and Product Validity to a Specific Day of the Month" for more information.
If renewal_mode is set to 1, the following scenarios are possible:
- When cycle_fee_flags under rate_plan is set to
1:
- If calendar_dom under product is not set, then the cycle aligns with the reactivation date.
- If calendar_dom is set, the cycle aligns with either calendar_dom or the reactivation date, whichever is later.
- When cycle_fee_flags is set to 0, the cycle aligns with the billing date.
For a sample of the XML for a product in a deal with renewal_mode set to 1, see "Purchasing the Same Product or Discount Multiple Times" for more information.
You can update the value of renewal_mode by using the PCM_OP_PRICE_SET_PRICE_LIST opcode, but after customers subscribe to your deals, further updates to renewal_mode have no effect on the purchased products.
Activating Products in Plans and Deals on First Usage
When creating plans or deals in XML, you can specify to activate all products in a plan or deal when one of its products is activated on first usage. To do so, you use the first_usage flag in the <deal> element (for deals) and in the <plan> element (for plans).
Set the first_usage flag to one of the following:
-
yes: Activates all products in a deal or plan upon the first usage of any of its products.
For example, assume a deal contains products A, B, and C. If the first service a customer uses is in product B, all three products (A, B, and C) are activated at that time.
-
no: When one product in a deal or plan is activated on first usage, the other products in the plan or deal are not activated.
For example, assume a plan contains products A, B, and C. If the first service a customer uses is in product B, only product B is activated at that time. This is the default.
The following shows an example of a plan with the first_usage flag set:
<plan ondemand_billing="no" first_usage="yes">
<plan_name>Plan01</plan_name>
<description>Plan01</description>
<service_deal>
<service_name>/service/ip</service_name>
<deal_name>Deal01</deal_name>
<bal_info_index>0</bal_info_index>
<subscription_index>0</subscription_index>
</service_deal>
</plan>Using Date Ranges for Versioning
When creating products in XML, you can add rate plans with new date ranges to create new versions of the same product.
You use the date_range_type attribute for the product to specify whether existing subscriptions move to the new charge or continue with the old charge.
BRM determines which rate plan to apply based on the value of date_range_type as follows:
- EVENT_DATE: The charge event date determines which rate plan is applied. Any existing subscriptions will use the new rate plan after the existing subscription's end date. This is the default behavior.
- PURCHASE_DATE: The original purchase date determines which rate
plan is applied. Any existing subscriptions will continue to use the old rate plan.
Any new subscriptions purchased within the new rate plan's date range will use the
new rate plan.
Note:
If a customer transfers their subscription as part of a service group transfer and date_range_type is set to PURCHASE_DATE, the rate plan will be determined based on the service transfer date, not the original purchase date. - INSTANTIATED_DATE: The original service instantiation date determines which rate plan is applied. Any existing subscriptions will continue to use the old rate plan. Any new subscriptions instantiated during the new rate plan's date range will use the new rate plan. This option is useful if your services often have a long delay between purchase and instantiation date. It allows customers with existing subscriptions to continue with the old rate plan, while those who purchase under the old rate plan can take advantage of the new rate plan if it comes into effect before their new service is available.
The following shows an example of a product using date_range_type:
<?xml version="1.0" encoding="UTF-8"?>
<price_list version="7.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="price_list.xsd">
<product partial="no" type="subscription" date_range_type="EVENT_DATE">
<product_name>prod1</product_name>
<product_code>prod1</product_code>
...
</product>
</price_list>The following examples describe how the value of date_range_type affects the rate plan applied. In the examples, you have an existing product with a rate plan that credits 1GB of free data every week. You add a new rate plan crediting 1.5GB, set the end date of the old rate plan to June 10, and set the start date for the new rate plan to June 11. Depending on the value of date_range_type for the product, the following happens:
- If dateRangeImpactType is set to EVENT_DATE, all subscriptions get 1GB until June 10 and 1.5GB thereafter.
- If dateRangeImpactType is set to PURCHASE_DATE, subscriptions purchased before June 10 continue to get 1GB, even for events occurring after June 10. Subscriptions purchased after June 10 get 1.5GB.
- If dateRangeImpactType is set to INSTANTIATED_DATE, subscriptions instantiated before June 10 continue to get 1GB, even for events occurring after June 10. Subscriptions instantiated after June 10 get 1.5GB, even if they were purchased before.
Defining Product Specification Attributes for Pricing Components
When creating products, discounts, chargeshares, deals, and packages in XML, you can define product specification attributes to store information used by external applications, such as enterprise product catalogs, beyond what is provided in BRM.
You define product specification attributes in attributes elements with nested name and value elements. The following examples show product specification attributes for each pricing component:
- Products:
<product partial="no" type="subscription"> <product_name>Product with product specification attributes</product_name> <product_code>Product 1</product_code> <priority>0.0</priority> <description>cycle_forward_monthly</description> <permitted>/service/ip</permitted> ... <attributes> <name>Lifecycle Status</name> <value>Test</value> </attributes> <attributes> <name>External Reference ID</name> <value>09876</value> </attributes> ... </product> - Discounts:
<discount mode="parallel" type="subscription"> <discount_name>Discount with product specification attributes</discount_name> <discount_code>Discount 1</discount_code> <priority>0.0</priority> <permitted>/service/ip</permitted> ... <attributes> <name>Lifecycle Status</name> <value>Suspend</value> </attributes> <attributes> <name>External Reference ID</name> <value>98645</value> </attributes> ... </discount> - Chargeshares:
<sponsorship> <sponsorship_name>Standard GSM Charge Share</sponsorship_name> ... <attributes> <name>Lifecycle Status</name> <value>Retired</value> </attributes> <attributes> <name>External Reference ID</name> <value>24601</value> </attributes> ... </sponsorship> - Deals:
<deal customization_flag="optional" ondemand_billing="no"> <deal_name>Deal with product specification attributes</deal_name> <permitted>/service/ip</permitted> <deal_product status="active"> <product_name>Product with product specification attributes</product_name> <product_code>Product 1</product_code> <quantity>1.0</quantity> </deal_product> <deal_discount status="active"> <discount_name>Discount with product specification attributes</discount_name> <discount_code>Discount 1</discount_code> <quantity>1.0</quantity> </deal_discount> ... <attributes> <name>Lifecycle Status</name> <value>Draft</value> </attributes> <attributes> <name>External Reference ID</name> <value>8675309</value> </attributes> ... </deal> - Plans:
<plan ondemand_billing="no"> <plan_name>Plan with product specification attributes</plan_name> <service_deal> <service_name>/service/ip</service_name> <deal_name>Deal with product specification attributes</deal_name> </service_deal> ... <attributes> <name>Lifecycle Status</name> <value>Release</value> </attributes> <attributes> <name>External Reference ID</name> <value>011235813</value> </attributes> ... </plan>
Although BRM does not provide validation for these attributes by default, you can configure validations in the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING opcode. See "Validating Extended Attributes" in BRM Opcode Guide.
Storing and Managing Product Specification Attributes
When you import your pricing objects, product specification attributes are stored in an /offer_attribute_group object. The POID for the /offer_attribute_group object is stored in the PIN_FLD_ATTRIBUTE_OBJ field of the pricing object. For example, the flist for a deal with product specification attributes would contain the following:
0 PIN_FLD_POID POID [0] 0.0.0.1 /deal 95359 0
0 PIN_FLD_ATTRIBUTE_OBJ POID [0] 0.0.0.1 /offer_attribute_group 96383 0You can use the loadpricelist utility to manage product specification attributes as follows:
- Load a price list to add or modify product specification attributes. The values in the /offer_attribute_group objects are updated, but the PIN_FLD_ATTRIBUTE_OBJ value for the pricing object remains the same.
- Load a price list to remove product specification attributes from a pricing object. The attributes are removed from the /offer_attribute_group object. If you remove all product specification attributes from a pricing object, the value of PIN_FLD_ATTRIBUTE_OBJ is changed to a null value (POID [0] 0.0.0.0 0 0), and the empty /offer_attribute_group object remains.
- Download a price list that includes product specification attributes from the database. The utility converts PIN_FLD_ATTRIBUTE_OBJ to attributes elements with the appropriate name and value elements in the output XML.
- Delete a pricing object from the database. Any associated /offer_attribute_group objects are also deleted.
Stop Rating Inactive, Canceled, or SuspendedActive Accounts
When configuring cycle rates and purchase rates in XML, you can specify whether BRM should continue charging or stop charging accounts that have the following:
-
An Inactive status
-
A Cancelled status
-
A SuspendedActive custom life cycle state
Note:
This option is valid only if your system includes a custom life cycle state named SuspendedActive. See "Creating Custom Service Life Cycles" in BRM Managing Customers.
For each cycle and purchase rate defined in your pricing XML file, set the <event_rating_map> flag element to one of the following:
-
not_rate_inactive: Specifies not to apply charges to inactive accounts.
-
not_rate_cancelled: Specifies not to apply charges to canceled accounts.
-
rate_lifecycle_suspend: Specifies to continue applying charges to suspended accounts.
For example, the following specifies to continue applying charges to suspended accounts:
<event_rating_map flag="rate_lifecycle_suspend" incr_unit="none" min_unit="none" rounding_rule="nearest" timezone_mode="event" tod_mode="start_time">Setting Loan Thresholds for Plans
When creating credit limits for plans in XML, you can use the following elements to set balance thresholds below which a customer is offered a loan:
- <thresholds_loan>: When this percent of the balance is consumed, the customer is offered a loan. The percentage must be in 5% increments.
- <thresholds_fixed_loan>: When the balance falls below this fixed number, which must be greater than the credit floor and less than the credit ceiling, the customer is offered a loan.
You can set multiple thresholds within the elements, delimited by a space.
When the customer subscribes to the plan, the thresholds are stored in the /config/credit_profile object associated with their balance group. For more information about loan thresholds and what happens when they are breached, see "About Loan Thresholds" in BRM Configuring and Collecting Payments.
The following sample XML entries specify several threshold elements. The <thresholds_loan> and <thresholds_fixed_loan> elements are used for offering loans and the <thresholds> and <thresholds_fixed> elements are used for different notifications or automatic top-ups:
<plan ondemand_billing="no">
<plan_name>Plan for Loan Thresholds</plan_name>
<plan_code>123456</plan_code>
<description />
<credit_limit>
<resource_id>840</resource_id>
<limit>100</limit>
<thresholds>30 60 90</thresholds>
<thresholds_fixed>25 50 75</thresholds_fixed>
<thresholds_loan>35 65 95</thresholds_loan>
<thresholds_fixed_loan>20 60 80</thresholds_fixed_loan>
<floor>10</floor>
</credit_limit>
...
</plan>Enabling Dynamic Credit Floors in Plans
You can set BRM to generate a dynamic credit floor from the granted amounts from the sub-balances that are valid for the current cycle for the resource (for example, minutes). To do so, you use the dynamic_floor flag in the <credit_limit> element.
Set the dynamic_floor flag to one of the following:
-
1: Sets the credit floor to be based on the granted amounts from the sub-balances that are valid for the current cycle for the resource (for example, minutes).
For example, assume a customer has a usual monthly grant of 10GB of data, but for a single charge period has purchased a booster pack of 5 GB of data. The dynamic credit floor updates the credit floor to 15 GB for the current cycle, and then reverts to 10 GB at the start of the next cycle.
-
0: Does not set a dynamic credit floor. In this case, the fixed credit floor will be used. This is the default.
The following shows an example of a plan with the dynamic_floor flag set:
<plan ondemand_billing="no">
<plan_name>Plan for Loan Thresholds</plan_name>
<plan_code>123456</plan_code>
<description />
<credit_limit>
<resource_id>840</resource_id>
<limit>100.0</limit>
<thresholds>50 60</thresholds>
<thresholds_fixed>80</thresholds_fixed>
<thresholds_loan>20 40</thresholds_loan>
<thresholds_fixed_loan>40</thresholds_fixed_loan>
<floor>0.0</floor>
<dynamic_floor>1</dynamic_floor>
</credit_limit>
...
</plan>Creating Tax Selectors for Products
You can create tax selectors for products so that defined tax codes can be applied based on attributes in the /account, /service, /event, or /profile objects.
To do so, you define the selector using the <tax_selector> element and then set the name of the selector in the <tax_selector_name> element under the <product> element.
The elements under the <tax_selector> element are:
-
selector_name: Text containing the name of the selector.
-
selector_rules: Container for a set of selection criteria.
-
criteria: The selection criteria for the tax code. This has an attribute, operator, which specifies the comparison type. It must be either equal or in. The operator is case-sensitive, and the default is equal.
-
object_class: The name of the class containing the element to be compared.
-
elem_name: The specific child element of the object in the <object_class> element that contains the field to be compared. This can contain multiple layers, separated by periods, for example, SUB_BAL_IMPACTS.SUB_BALANCES.
-
field_name: The name of the field containing the data to be compared.
-
field_value: The value that is to be compared with the contents of the field specified by <field_name>.
-
code: The tax code that should be mapped if the comparison is successful.
The following shows an example of <tax_selector> configuration:
<tax_selector>
<selector_name>tax1</selector_name>
<selector_rules>
<criteria operator="equal">
<object_class>/account</object_class>
<elem_name> PIN_FLD_NAMEINFO </elem_name>
<field_name>PIN_FLD_CITY</field_name>
<field_value>Bangalore</field_value>
</criteria>
<criteria operator="equal">
<object_class>/event</object_class>
<field_name>PIN_FLD_NAME</field_name>
<field_value>cycle_fwd</field_value>
</criteria>
<code>VAT</code>
</selector_rules>
<selector_rules>
<criteria operator="equal">
<object_class>/account</object_class>
<elem_name> PIN_FLD_NAMEINFO </elem_name>
<field_name>PIN_FLD_CITY</field_name>
<field_value>VSKP</field_value>
</criteria>
<criteria operator="equal">
<object_class>/event</object_class>
<field_name>PIN_FLD_NAME</field_name>
<field_value>cycle_arrear</field_value>
</criteria>
<tax_code>VAT1</tax_code>
</selector_rules>
</tax_selector> Following is an example of a product configuration containing the <tax_selector_name> element:
<product date_range_type="EVENT_DATE" partial="no" type="subscription">
. . .
<event_rating_map incr_unit="none" min_unit="none" rounding_rule="nearest" timezone_mode="event" tod_mode="start_time">
. . .
<rate_plan advance_billing_unit="day" tax_when="now">
<rate_plan_name>charge2$-session</rate_plan_name>
<currency_id>840</currency_id>
<event_type>/event/session</event_type>
<tax_selector_name>tax1</tax_selector_name>
<advance_billing_offset>0</advance_billing_offset>
<cycle_fee_flags>0</cycle_fee_flags>
. . .
</rate_plan>
. . .
</event_rating_map>
</product>Creating Tax Exemption Selectors for Products
You can create tax exemption selectors for products so that defined tax exemptions can be applied based on attributes in the /account, /service, /event, or /profile objects. For more information about tax exemptions, see "About Tax Exemptions" in BRM Calculating Taxes.
To do so, you define the selector using the <tax_exemption_selector> element and then set the name of the selector in the <selector_name> element under the <product> element.
The elements under the <tax_exemption_selector> element are:
-
selector_name: Text containing the name of the selector.
-
selector_rules: Container for a set of selection criteria.
-
criteria: The selection criteria for the tax exemption. This has an attribute, operator, which specifies the comparison type. It must be either equal or in. The operator is case-sensitive, and the default is equal.
-
object_class: The name of the class containing the element to be compared.
-
elem_name: The specific child element of the object in the <object_class> element that contains the field to be compared. This can contain multiple layers, separated by periods, for example, SUB_BAL_IMPACTS.SUB_BALANCES.
-
field_name: The name of the field containing the data to be compared.
-
field_value: The value that is to be compared with the contents of the field specified by <field_name>.
-
code: The exemption code that should be mapped if the comparison is successful.
The following shows an example of <tax_exemption_selector> configuration:
<tax_exemption_selector>
<selector_name>tax_exempt</selector_name>
<selector_rules>
<criteria operator="equal">
<object_class>/account</object_class>
<elem_name> PIN_FLD_NAMEINFO </elem_name>
<field_name>PIN_FLD_CITY</field_name>
<field_value>Bangalore</field_value>
</criteria>
<criteria operator="equal">
<object_class>/event</object_class>
<field_name>PIN_FLD_NAME</field_name>
<field_value>cycle_fwd</field_value>
</criteria>
<code>student</code>
</selector_rules>
<selector_rules>
<criteria operator="equal">
<object_class>/account</object_class>
<elem_name> PIN_FLD_NAMEINFO </elem_name>
<field_name>PIN_FLD_CITY</field_name>
<field_value>VSKP</field_value>
</criteria>
<criteria operator="equal">
<object_class>/event</object_class>
<field_name>PIN_FLD_NAME</field_name>
<field_value>cycle_arrear</field_value>
</criteria>
<code>employee</code>
</selector_rules>
</tax_exemption_selector>Following is an example of a product configuration containing the <selector_name> element:
<product partial="no" type="subscription">
<product_name>tax_prod_RPS</product_name>
<product_code>tax_prod_RPS</product_code>
<priority>0.0</priority>
<description>Sample product</description>
<permitted>/service/ip</permitted>
<tax_supplier>TS1</tax_supplier>
<selector_name>tax_exempt</selector_name>
. . .
</product>