31 XML Examples of Creating Pricing Components
Learn how to use the XML examples as a guideline for creating your own pricing components using the Oracle Communications Pricing Design Center (PDC) XML Pricing Interface.
Topics in this document:
- Bundle Configuration Examples
- Charge Offer Configuration Examples
- Discount Offer Configuration Examples
- Package Configuration Examples
- Selector Configuration Examples
For a list of PDC XML tags that you can use to create pricing components, see "PDC XML Tags".
Bundle Configuration Examples
To configure bundle functionality by using the PDC XML Pricing Interface, see the following examples:
Activating Offers in Bundles
When creating bundles in XML, you can specify whether to activate all charge offers in a bundle when one of the charge offers is activated on first usage. To do so, you use the <firstUsageActivation> element under the <bundledProductOffering> element.
Set the <firstUsageActivation> element to one of the following:
-
true: Activates all charge offers in the bundle upon first usage of any charge offer in the bundle.
For example, assume a bundle contains charge offers A, B, and C. If the first service a customer uses is in charge offer B, all charge offers (A, B, and C) are activated at that time.
-
false: When one charge offer in a bundle is activated on first usage, the other charge offers in the bundle are not activated.
For example, assume a bundle contains charge offers A, B, and C. If the first service a customer uses is in charge offer B, only charge offer B is activated at that time. This is the default.
The following shows an example of a bundle with the <firstUsageActivation> element set:
<bundledProductOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Bundle for Data</name>
<internalId>InternalID</internalId>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>TelcoGsmTelephony</productSpecName>
<billOnPurchase>false</billOnPurchase>
<customize>OPTIONAL</customize>
<firstUsageActivation>true</firstUsageActivation>
<groupBalanceElements>false</groupBalanceElements>
<bundledProductOfferingItem>
…….
…….
…….
</bundledProductOfferingItem>
</bundledProductOffering>Configuring Add-On Charge Offers In Bundles
When creating bundles in XML, you can include add-on charge offers. By default, all charge offers in bundles are base charge offers, which means they can be purchased without any prerequisites. Add-on charge offers require customers to own a valid base charge offer.
You configure an add-on charge offer in a bundle by doing the following:
-
Including the <addOnOfferingValidityMode> element under <bundledProductOfferingItem>.
-
Specifying the add-on charge offer's validity. The add-on charge offer's validity start date is the end date of a charge offer that you specify. For example, assume charge offer A has a validity period from June 1 through June 15. If you specify to align add-on charge offer B's validity period with charge offer A, charge offer B's validity start date would be June 15.
You specify the charge offer on which to align an add-on charge offer's validity dates by setting the <addOnOfferingValidityMode> element to one of the following:
-
BASE_OFFER: Aligns the validity dates with the specified base charge offer.
-
BASE_OFFER_EXPIRY_FIRST: Aligns the validity dates with the active base charge offer that expires first.
-
BASE_OFFER_EXPIRY_LAST: Aligns the validity dates with the active base charge offer that expires last.
-
BASE_OR_ADD_ON_OFFER_EXPIRY_FIRST: Aligns the validity dates with the active charge offer that expires first.
-
BASE_OR_ADD_ON_OFFER_EXPIRY_LAST: Aligns the validity dates with the active charge offer that expires last.
-
-
If you set <addOnOfferingValidityMode> to BASE_OFFER, add the <baseChargeOfferingName> element set to the name of the base charge offer on which to set validity dates.
Note:
Do not include the <baseChargeOfferingName> element for the other <addOnOfferingValidityMode> values: BASE_OFFER_EXPIRY_FIRST, BASE_OFFER_EXPIRY_LAST, BASE_OR_ADD_ON_OFFER_EXPIRY_FIRST, and BASE_OR_ADD_ON_OFFER_EXPIRY_LAST.
-
Setting the validity period for all charges in the add-on charge offer to the default value (immediate to never expires).
To do so, add the following elements under <purchaseStart>, <purchaseEnd>, <usageStart>, <usageEnd>, <cycleStart>, and <cycleEnd>:
-
<offset> set to 0
-
<mode> set to NOW_TO_NEVER
-
The following shows sample XML for creating an add-on charge offer that uses the same validity period as the Sample01 base charge offer:
<bundledProductOfferingItem>
<purchaseStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</purchaseStart>
<purchaseEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</purchaseEnd>
<usageStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</usageStart>
<usageEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</usageEnd>
<cycleStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</cycleStart>
<cycleEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</cycleEnd>
<status>1</status>
<statusCode>0</statusCode>
<renewalMode>false</renewalMode>
<quantity>1.0</quantity>
<purchaseChargeAdjustment>0.0</purchaseChargeAdjustment>
<usageChargeAdjustment>0.0</usageChargeAdjustment>
<cycleChargeAdjustment>0.0</cycleChargeAdjustment>
<purchaseMode>NEW_INSTANCE</purchaseMode>
<addOnOfferingValidityMode>BASE_OFFER</addOnOfferingValidityMode>
<baseChargeOfferingName>Sample01</baseChargeOfferingName>
<chargeOfferingName>MyChargeOffer</chargeOfferingName>
</bundledProductOfferingItem>Configuring Proration for Offers in Bundles
When creating bundles in XML, you can set how to prorate cycle charges and discounts at the offer level.
To configure proration for an offer in a bundle, set the <prorationBasedOn> element under <bundledProductOfferingItem> to one of the following:
-
PRORATE_30_DAYS: Prorated charges and discounts are based on a 30-day month.
-
PRORATE_DAYS_IN_MONTH: Prorated charges and discounts are based on the actual number of days in a month, such as 30 for June or 31 for May.
-
Not Set: Prorated charges are calculated according to the system-wide setting in the CM pin.conf file. See "Examples of 30-Day-Based Proration" in BRM Configuring and Running Billing.
The following shows sample XML for configuring the Sample01 charge offer to use 30-day proration:
<bundledProductOfferingItem>
...
<status>1</status>
<statusCode>0</statusCode>
<renewalMode>false</renewalMode>
<quantity>1.0</quantity>
<purchaseChargeAdjustment>0.0</purchaseChargeAdjustment>
<usageChargeAdjustment>0.0</usageChargeAdjustment>
<cycleChargeAdjustment>0.0</cycleChargeAdjustment>
<prorationBasedOn>PRORATE_30_DAYS<prorationBasedOn>
<purchaseMode>NEW_INSTANCE</purchaseMode>
<addOnOfferingValidityMode>BASE_OFFER_EXPIRY_FIRST</addOnOfferingValidityMode>
<chargeOfferingName>Sample01</chargeOfferingName>
</bundledProductOfferingItem>Purchasing the Same Offer in a Bundle Multiple Times
When creating bundles in XML, you can specify what happens if customers purchase the same charge offer or discount offer more than once.
For both charge offers and discount offers, you can specify whether the additional offer is purchased as a new subscription or a replacement of the existing subscription. To do so, in the definition of the bundle containing the charge offer or discount offer, set the value for the <purchaseMode> element under the <bundledProductOfferingItem> element to one of the following:
-
NEW_INSTANCE: The additional charge offer or discount offer 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.
-
OVERWRITE: The additional charge offer or discount offer replaces the existing subscription. The existing subscription is canceled, any configured proration is applied, and the new subscription is created, with all balance impacts and validity periods set as though for a new purchase.
For example, on June 1st, a customer purchases an add-on bundle that grants 3GB of data and is valid for 7 days. On June 3rd, after using 1GB, they purchase the bundle again. The old charge offer is canceled, any remaining balance is prorated, and the new 3GB balance is created, with a validity end date of June 10th.
For both charge offers and discount offers, you can also specify whether the additional offer is purchased as an extension of the existing subscription if it is purchased within a specified grace period. To do so, in the definition of charge offers, you can also set the value for the <purchaseMode> element under the <bundledProductOfferingItem> element to one of the following:
-
LONGEST_DATE: The additional charge offer is purchased as an extension to the existing subscription if it is purchased within the grace period. The new balance impacts are added to the existing balance group. The validity period for the balance is then set to either the old validity end date or the new validity end date, whichever is later.
You specify the grace period under the <bundledProductOfferingItem> by setting the <gracePeriodOffset> element to the amount of time and the <gracePeriodUnit> element to Seconds, Minutes, Hours, or Days.
For example, on June 1st, a customer purchases an add-on bundle that grants 3GB of data, is valid for 7 days, and has a grace period of 4 days. On June 3rd, after using 1GB, they purchase the bundle again. The new 3GB balance is added to the remaining balance, for a total of 5GB. BRM compares the validity periods of the old and new charge offer and sets the validity end date for the total balance to the later of the two end dates, June 10th.
-
EXTEND: The additional charge offer is purchased as an extension to the existing subscription if it is purchased with the grace period. The new balance impacts are added to the existing balance group. The validity period for the balance is then set by adding the new validity period to whatever remains of the old validity period.
You specify the grace period under the <bundledProductOfferingItem> by setting the <gracePeriodOffset> element to the amount of time and the <gracePeriodUnit> element to Seconds, Minutes, Hours, or Days.
For example, on June 1st, a customer purchases an add-on bundle that grants 3GB of data, is valid for 7 days, and has a grace period of 4 days. On June 3rd, after using 1GB, they purchase the bundle again. The new 3GB balance is added to the remaining balance, for a total of 5GB. BRM adds the validity period of the new charge offer to the old charge offer, and sets the validity end date for the total balance to June 15th.
The following shows a sample of the XML for a charge offer in a bundle with <purchaseMode> set to EXTEND, <gracePeriodOffset> set to 5, and <gracePeriodUnit> set to Day.
<BundledProductOffering>
<name>Extend Bundle</name>
<description>Bundle with Extend Purchase Mode</description>
<internalId>InternalID</internalId>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>TelcoGsm</productSpecName>
<billOnPurchase>false</billOnPurchase>
<customize>OPTIONAL</customize>
<groupBalanceElements>false</groupBalanceElements>
<bundledProductOfferingItem>
<purchaseStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</purchaseStart>
<purchaseEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</purchaseEnd>
<usageStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</usageStart>
<usageEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</usageEnd>
<cycleStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</cycleStart>
<cycleEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</cycleEnd>
<status>1</status>
<statusCode>0</statusCode>
<renewalMode>true</renewalMode>
<quantity>1.0</quantity>
<purchaseChargeAdjustment>0.0</purchaseChargeAdjustment>
<usageChargeAdjustment>0.0</usageChargeAdjustment>
<cycleChargeAdjustment>0.0</cycleChargeAdjustment>
<purchaseMode>EXTEND</purchaseMode>
<gracePeriodOffset>5</gracePeriodOffset>
<gracePeriodUnit>Day</gracePeriodUnit>
<chargeOfferingName>Charge Offer - Purchase Fee</chargeOfferingName>
</bundledProductOfferingItem>
</BundledProductOffering>The following shows a sample of the XML for a discount offer in a bundle with <purchaseMode> set to OVERWRITE.
<bundledProductOfferingItem>
<purchaseStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</purchaseStart>
<purchaseEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</purchaseEnd>
<usageStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</usageStart>
<usageEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</usageEnd>
<cycleStart>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</cycleStart>
<cycleEnd>
<offset>0</offset>
<mode>NOW_TO_NEVER</mode>
</cycleEnd>
<status>1</status>
<statusCode>0</statusCode>
<renewalMode>true</renewalMode>
<quantity>1.0</quantity>
<purchaseChargeAdjustment>0.0</purchaseChargeAdjustment>
<usageChargeAdjustment>0.0</usageChargeAdjustment>
<cycleChargeAdjustment>0.0</cycleChargeAdjustment>
<purchaseMode>OVERWRITE</purchaseMode>
<alterationOfferingName>Discount Offer - Usage Discount</alterationOfferingName>
</bundledProductOfferingItem>Setting Charge Offer Cycle Alignment for Reactivated Bundles
When creating bundles in XML, you can specify when the cycle should align for charge offers if a customer suspends then reactivates the bundle.
In the definition of the bundle containing the charge offer, set the value for the <renewalMode> element under the <bundledProductOfferingItem> element to true or false. This setting is not valid for discount offers.
If <renewalMode> is set to false, the cycle aligns as described in "Aligning Recurring Charges and Product Validity to a Specific Day of the Month".
If <renewalMode> is set to true, the following scenarios are possible:
- When <cycleFeeFlag> under chargeRatePlan is set to
1:
- If <purchaseCycleDOM> under chargeOffering is not set, the cycle aligns with the reactivation date.
- If <purchaseCycleDOM> is set, the cycle aligns with either <purchaseCycleDOM> or the reactivation date, whichever is later.
- When <cycleFeeFlag> is set to 0, the cycle aligns with the billing date.
For sample of the XML for a charge offer in a bundle with <renewalMode> set to true, see "Purchasing the Same Offer in a Bundle Multiple Times".
Transitioning Bundles
When creating bundle transitions in XML, you can configure how PDC applies charges when customers transition bundles in the middle of their billing cycle by using the <prorationType> element under the <bundleTransition> element.
Set the <prorationType> element to one of the following:
-
PRORATE_CHARGE: Specifies to prorate charges for both bundles. This is the default.
-
ORIGINAL_CHARGE: Specifies to apply the full charges from the original bundle.
-
TRANSFER_CHARGE: Specifies to apply the full charges from the new bundle.
The following shows an example of a bundle transition with the <prorationType> element set:
<bundleTransition xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>sample package transition/name>
<internalId>InternalID</internalId>
<pricingProfileName>Subscription</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<active>true</active>
<timeRange>0/inf</timeRange>
<waivePurchaseFee>true</waivePurchaseFee>
<waiveCancelFee>true</waiveCancelFee>
<productSpecName>TelcoGsmTelephony</productSpecName>
<prorationType>ORIGINAL_CHARGE</prorationType>
<type>GENERATION_CHANGE</type>
<fromBundleName>Bundle A</fromPackageName>
<toBundleName>Bundle B</toPackageName>
</bundleTransition>Charge Offer Configuration Examples
To configure charge offer functionality by using the PDC XML Pricing Interface, see the following examples:
- Aligning Recurring Charges and Product Validity to a Specific Day of the Month
- Enforcing or Exceeding Credit Limits
- Offering Hourly Balance Impacts
- Consuming Granted Allowances Before Applying Usage Charges
- Prorating Recurring Fees and Rollovers
- Setting Full Day Proration
- Setting Taxation for Charges
- Using a Tax Exemption Selector
- Sharing Products Automatically with Sharing Group Members
- Using Date Ranges for Versioning
Aligning Recurring Charges and Product Validity to a Specific Day of the Month
When creating charge offers in XML, you can use the <purchaseCycleDOM> and <cycleFeeFlag> 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 offer validity to a specific day of the month, set <purchaseCycleDOM> to an integer from 1-31 and set <cycleFeeFlag> to 1.
- To align recurring charges and offer validity to the billing date, set <purchaseCycleDOM> to 0. The value of <cycleFeeFlag> is irrelevant in this scenario.
- To align recurring charges to the billing date but set offer validity to a specific day of the month, set <purchaseCycleDOM> to an integer from 1-31 and set <cycleFeeFlag> to 0.
Caution:
You cannot change the <purchaseCycleDOM> value for a charge offer after it has been purchased. If you create a new version of the charge offer with a different value in <purchaseCycleDOM>, 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 apply recurring charges for a charge offer on the 22nd day of the month, the XML input file would include the following:
<chargeRatePlan xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Charge for a Specific Day of the Month</name>
<pricingProfileName>Subscription</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<applicableRums>Occurrence</applicableRums>
<applicableQuantity>ORIGINAL</applicableQuantity>
<taxTime>NONE</taxTime>
<todMode>START_TIME</todMode>
<applicableQtyTreatment>CONTINUOUS</applicableQtyTreatment>
<permittedName>TelcoGsmTelephony</permittedName>
<permittedType>PRODUCT</permittedType>
<eventName>EventBillingProductFeeCycleCycle_forward_monthly</eventName>
<cycleFeeFlag>1</cycleFeeFlag>
<billOffset>0</billOffset>
<subscriberCurrency>
...
</subscriberCurrency>
</chargeRatePlan>
<chargeOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Charge Offer for a Specific Day of the Month</name>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>TelcoGsmTelephony</productSpecName>
<offerType>SUBSCRIPTION</offerType>
<priority>1</priority>
<partial>false</partial>
<purchaseMin>-1.0</purchaseMin>
<purchaseMax>-1.0</purchaseMax>
<ownMin>-1.0</ownMin>
<ownMax>-1.0</ownMax>
<applicableQuantity>REMAINING</applicableQuantity>
<purchaseCycleDOM>22</purchaseCycleDOM>
<dateRangeImpactType>INSTANTIATED_DATE</dateRangeImpactType>
<chargeEventMap>
<eventName>EventBillingProductFeeCycleCycle_forward_monthly</eventName>
<validIfCancelled>false</validIfCancelled>
<validIfInactive>false</validIfInactive>
<timezoneMode>EVENT</timezoneMode>
<minQuantity>0</minQuantity>
<minQuantityUnit>NONE</minQuantityUnit>
<incrementQuantity>1</incrementQuantity>
<incrementQuantityUnit>NONE</incrementQuantityUnit>
<roundingMode>NEAREST</roundingMode>
<prorateFirst>PRORATE_CHARGE</prorateFirst>
<prorateLast>PRORATE_CHARGE</prorateLast>
<chargeRatePlanInfo>
<targetEngine>RRE</targetEngine>
</chargeRatePlanInfo>
<chargeRatePlanName>Charge for a Specific Day of the Month</chargeRatePlanName>
</chargeEventMap>
</chargeOffering>
</pdc:PricingObjectsJXB>If a customer with a billing date of the 14th of the month purchased the charge offer 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 <purchaseCycleDOM> 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 <cycleFeeFlag> 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 charge offer's duration, it would only be valid until the 22nd of the month (the <purchaseCycleDOM> date.) If the charge offer was valid for three months, the final fee would be prorated to cover the period from March 14 to March 22.
Note:
For charge offers in bundles 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 <renewalMode> element under the <bundledProductOfferingItem> element. See "Setting Charge Offer Cycle Alignment for Reactivated Bundles" for information about how <renewalMode> interacts with <purchaseCycleDOM> and <cycleFeeFlag>.Enforcing or Exceeding Credit Limits
When creating charges in XML, you can specify whether to enforce credit limits, or let customers exceed them.
To do so, set the <enforceCreditLimit> element under the price tier to one of the following:
- NORMAL: Enforce the credit limit. The subscription succeeds, but customers do not exceed 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 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 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 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 next cycle.
- INSUFFICIENT_BALANCE: 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 minimum amount for currency resources in the <creditLimitMinimumAmount> element. By default, this is set to 0, which means the subscription fails if the balance is less than the full amount. <creditLimitMinimumAmount> is not applicable for noncurrency resources.
- Whether or not to prorate the service according to the minimum amount in the <creditLimitProrateQuantity> element. By default, this is set to true and the service will be prorated. Set this to false to grant the full service for the minimum amount.
This option is useful 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 INSUFFICIENT_BALANCE options, you can also configure the following:
- The maximum number of times to retry the subscription before it fails. Configure this in the <retryMaxCount> element of the charge offer. The default is 0, which sends the failure notification immediately without retrying.
- The frequency of subsequent retries. Configure this in the
<retryOffset> and <retryUnit> elements of the charge
offer.
The default values are 1 for <retryOffset> is and DAY for <retryUnit>. The possible values for <retryUnit> are:
- SECOND
- MINUTE
- HOUR
- DAY
- WEEK
- MONTH
- YEAR
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" for more information about setting this parameter.
Table 31-1 Mapping XML Values and UI Labels
| XML Value | UI Label |
|---|---|
| NORMAL | Prorate service according to available balance |
| DEFAULT | Use available balance, track remainder as negative account balance |
| LOAN | Use available balance, grant loan for remainder |
| DEDUCT_RENTAL | Use available balance, track remainder as outstanding |
| OUTSTANDING_AMOUNT | Do not use available balance, track entire amount as outstanding |
| RENTAL_FAILURE | Subscription fails |
| AUTO_RENEW_CANCEL | Subscription fails and is canceled |
| SKIP_CYCLE | Skip subscription charges until next cycle |
| INSUFFICIENT_BALANCE | Charge minimum configured amount |
The following XML 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.
<chargeRatePlan xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Credit Limit Sample Rate Plan</name>
<internalId>InternalID</internalId>
<pricingProfileName>Subscription</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<applicableRums>RECURRING</applicableRums>
<applicableQuantity>ORIGINAL</applicableQuantity>
<taxTime>NONE</taxTime>
<todMode>START_TIME</todMode>
<applicableQtyTreatment>CONTINUOUS</applicableQtyTreatment>
<permittedName>TelcoGsmTelephony</permittedName>
<permittedType>PRODUCT</permittedType>
<eventName>EventBillingProductFeeCycleCycle_forward_monthly</eventName>
<cycleFeeFlag>0</cycleFeeFlag>
<billOffset>0</billOffset>
<subscriberCurrency>
<currencyCode>USD</currencyCode>
<crpRelDateRange>
<absoluteDateRange>
<startDate>0</startDate>
<endDate>inf</endDate>
</absoluteDateRange>
<crpCompositePopModel>
<name>Pricing</name>
<recurringPopModel>
<priceTier>
<lowerBound>NO_MIN</lowerBound>
<tierBasis>
<rumTierExpression/>
</tierBasis>
<rumName>RECURRING</rumName>
<enforceCreditLimit>INSUFFICIENT_BALANCE</enforceCreditLimit>
<creditLimitProrateQuantity>true</creditLimitProrateQuantity>
<tierRange>
<upperBound>NO_MAX</upperBound>
<recurringCharge>
<price>20.0</price>
<unitOfMeasure>NONE</unitOfMeasure>
<balanceElementNumCode>840</balanceElementNumCode>
<discountable>true</discountable>
<priceType>CONSUMPTION</priceType>
<proratable>true</proratable>
<impactType>SCALED</impactType>
<creditLimitMinimumAmount>10</creditLimitMinimumAmount>
</recurringCharge>
<recurringCharge>
<price>-30.0</price>
<unitOfMeasure>NONE</unitOfMeasure>
<balanceElementNumCode>840</balanceElementNumCode>
<discountable>true</discountable>
<priceType>GRANT</priceType>
<priceValidity>
<startValidityMode>IMMEDIATE</startValidityMode>
<endValidityMode>NEVER</endValidityMode>
<validityRange>0/inf</validityRange>
<relativeStartOffset>-1</relativeStartOffset>
<relativeEndOffset>-1</relativeEndOffset>
</priceValidity>
<proratable>true</proratable>
<impactType>SCALED</impactType>
<creditLimitMinimumAmount>-40</creditLimitMinimumAmount>
</recurringCharge>
</tierRange>
</priceTier>
</recurringPopModel>
</crpCompositePopModel>
</crpRelDateRange>
</subscriberCurrency>
</chargeRatePlan>
<chargeOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Credit Limit Sample Offer</name>
<internalId>InternalID</internalId>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>TelcoGsmTelephony</productSpecName>
<offerType>SUBSCRIPTION</offerType>
<priority>0</priority>
<partial>false</partial>
<purchaseMin>-1.0</purchaseMin>
<purchaseMax>-1.0</purchaseMax>
<ownMin>-1.0</ownMin>
<ownMax>-1.0</ownMax>
<applicableQuantity>REMAINING</applicableQuantity>
<purchaseCycleDOM>0</purchaseCycleDOM>
<expiryNotification>true</expiryNotification>
<subscriptionDueNotification>true</subscriptionDueNotification>
<dateRangeImpactType>EVENT_DATE</dateRangeImpactType>
<retryMaxCount>3</retryMaxCount>
<retryUnit>HOUR</retryUnit>
<retryOffset>6</retryOffset>
<chargeEventMap>
<eventName>EventBillingProductFeeCycleCycle_forward_monthly</eventName>
<validIfCancelled>false</validIfCancelled>
<validIfInactive>false</validIfInactive>
<validIfSuspendedActive>false</validIfSuspendedActive>
<timezoneMode>EVENT</timezoneMode>
<minQuantity>0</minQuantity>
<minQuantityUnit>NONE</minQuantityUnit>
<incrementQuantity>1</incrementQuantity>
<incrementQuantityUnit>NONE</incrementQuantityUnit>
<roundingMode>NEAREST</roundingMode>
<prorateFirst>PRORATE_CHARGE</prorateFirst>
<prorateLast>PRORATE_CHARGE</prorateLast>
<prorateCycle>PRORATE_CHARGE</prorateCycle>
<chargeRatePlanInfo>
<targetEngine>RRE</targetEngine>
</chargeRatePlanInfo>
<chargeRatePlanName>Credit Limit Sample Rate Plan</chargeRatePlanName>
<ratePlanIID>4d0f0720</ratePlanIID>
</chargeEventMap>
</chargeOffering>Offering Hourly Balance Impacts
When creating charges in XML, you can configure hourly validity periods for the balance impacts that make up charges. This is useful for creating short-lived rewards, like free games or minutes. Hourly validity applies to conditional or non-conditional noncurrency credit balance impacts.
To configure hourly validity, use the following under the priceTierValidityPeriod element:
- For credit balance impacts, under the priceValidity element,
set:
- startValidityMode to PERIOD_START.
- endValidityMode to RELATIVE_TO_START.
- relativeEndOffsetUnit to HOUR.
- For conditional balance impacts, under
periodConditionExpression, set:
- unit to HOUR.
- periodStartTime to IMMEDIATE.
The following shows sample XML that creates two conditional balance impacts defined in the price tier. The first debits USD 2.99 every day and the second credits ten games, valid for one day, once every four hours.
...
<priceTierValidityPeriod>
<lowerBound>0</lowerBound>
<validFrom>0</validFrom>
<priceTierRange>
<upperBound>NO_MAX</upperBound>
<fixedCharge>
<price>2.99</price>
<unitOfMeasure>NONE</unitOfMeasure>
<balanceElementNumCode>840</balanceElementNumCode>
<discountable>true</discountable>
<priceType>CONSUMPTION</priceType>
<periodConditionExpression>
<biConditionOperator>EQUAL_TO</biConditionOperator>
<unit>DAY</unit>
<value>1</value>
<periodStartTime>IMMEDIATE</periodStartTime>
</periodConditionExpression>
</fixedCharge>
<fixedCharge>
<price>-10.0</price>
<unitOfMeasure>NONE</unitOfMeasure>
<balanceElementNumCode>1000004</balanceElementNumCode>
<discountable>true</discountable>
<priceType>GRANT</priceType>
<priceValidity>
<startValidityMode>PERIOD_START</startValidityMode>
<endValidityMode>RELATIVE_TO_PERIOD_START</endValidityMode>
<validityRange>0/inf</validityRange>
<relativeStartOffset>-1</relativeStartOffset>
<relativeEndOffset>1</relativeEndOffset>
<relativeEndOffsetUnit>DAY</relativeEndOffsetUnit>
</priceValidity>
<periodConditionExpression>
<biConditionOperator>EQUAL_TO</biConditionOperator>
<unit>HOUR</unit>
<value>4</value>
<periodStartTime>IMMEDIATE</periodStartTime>
</periodConditionExpression>
</fixedCharge>
</priceTierRange>
</priceTierValidityPeriod>
...Because rounding time stamps for hourly charges would result in all hourly charges being valid for 24 hours, BRM does not round time stamps for charges with hourly validity, even if time-stamp rounding is enabled. For example, if a customer purchases a bundle that is valid for three hours at 3pm, it is valid until 6pm. However, if BRM applied time-stamp rounding, it would be valid until midnight.
Consuming Granted Allowances Before Applying Usage Charges
When configuring charges in XML, you can specify to consume a customer's granted allowance before charging any usage fees. For example, you could create a charge that first consumes a customer's monthly allowance of free movie rentals, charges $5 for the next five movie rentals, and then charges $4 for any subsequent movie rentals. You implement this functionality by adding to the charge a pricing tier with multiple ranges. For the example above, you would add a pricing tier with the following ranges:
-
Consume the entire monthly allowance of free movie rentals
-
One through five movie rentals: $5 per movie rental
-
Six movie rentals and beyond: $4 per movie rental
Note:
Consuming granted allowances before charging for usage fees is supported by the ECE rating engine only.
To configure charges that consume granted allowances before charging usage fees, add multiple price tier ranges. Under each <priceTierRange> element, include an <upperBoundExpression> element with one of the following sets of fields:
-
To consume a granted allowance, include the following entries under <upperBoundExpression>. Set <balanceElementNumCode> to the ID of the noncurrency balance element to consume, such as the ID for free movie rentals.
<balanceTBExpression> <balanceElementNumCode>100002</balanceElementNumCode> </balanceTBExpression>
-
To charge for usage, include the following entries under <upperBoundExpression>. Set <value> to the end value for the quantity range.
<numberTBExpression> <value>5</value> </numberTBExpression>
The following shows sample XML that creates a charge with two pricing tier ranges: one range for consuming a noncurrency balance element, and a second range from 0 through 600 for charging 50 cents per minute:
<priceTierValidityPeriod>
<lowerBound>0</lowerBound>
<validFrom>0</validFrom>
<priceTierRange>
<upperBoundExpression>
<balanceTBExpression>
<balanceElementNumCode>100002</balanceElementNumCode>
</balanceTBExpression>
</upperBoundExpression>
<scaledCharge>
<price>1.0</price>
<unitOfMeasure>NONE</unitOfMeasure>
<balanceElementNumCode>100002</balanceElementNumCode>
<discountable>true</discountable>
<priceType>CONSUMPTION</priceType>
<incrementStep>1.0</incrementStep>
<incrementRounding>NONE</incrementRounding>
</scaledCharge>
</priceTierRange>
<priceTierRange>
<upperBoundExpression>
<numberTBExpression>
<value>600</value>
</numberTBExpression>
</upperBoundExpression>
<scaledCharge>
<price>0.5</price>
<unitOfMeasure>MINUTE</unitOfMeasure>
<balanceElementNumCode>840</balanceElementNumCode>
<discountable>true</discountable>
<priceType>CONSUMPTION</priceType>
<incrementStep>1.0</incrementStep>
<incrementRounding>NONE</incrementRounding>
</scaledCharge>
</priceTierRange>
</priceTierValidityPeriod>Prorating Recurring Fees and Rollovers
When creating charge offers in XML, you use the following XML elements to specify how to apply cycle fees and rollovers when customers purchase, cancel, or change their billing day of month (DOM) in the middle of a billing cycle:
-
<prorateFirst>: Specifies how to apply cycle fees and rollovers when customers purchase subscriptions in the middle of their billing cycle.
-
<prorateLast>: Specifies how to apply cycle fees and rollovers when customers cancel subscriptions in the middle of their billing cycle.
-
<prorateCycle>: Specifies how to apply cycle fees when customers change their billing day of the month (DOM) during any billing cycle.
You can set these XML elements to one of the following:
-
NO_CHARGE: Do not apply a cycle fee.
-
FULL_CHARGE: Apply the full cycle fee.
-
PRORATE_CHARGE: Calculate the cycle fee based on the amount of time the subscription was owned in the billing cycle. This is the default.
The following sample XML entries specify to not apply cycle fees when customers purchase subscriptions in the middle of their billing cycle, to prorate cycle fees when customers cancel subscriptions in the middle of their billing cycle, and to apply full cycle fees when customers change their billing DOM during any billing cycle:
<chargeEventMap>
<eventName>EventDelayedSessionTelcoGsm</eventName>
<validIfCancelled>false</validIfCancelled>
<validIfInactive>false</validIfInactive>
<timezoneMode>EVENT</timezoneMode>
<minQuantity>1</minQuantity>
<minQuantityUnit>none</minQuantityUnit>
<incrementQuantity>1</incrementQuantity>
<incrementQuantityUnit>none</incrementQuantityUnit>
<roundingMode>NEAREST</roundingMode>
<prorateFirst>NO_CHARGE</prorateFirst>
<prorateLast>PRORATE_CHARGE</prorateLast>
<prorateCycle>FULL_CHARGE</prorateCycle>
<chargeRatePlanInfo>
<targetEngine>ECE</targetEngine>
</chargeRatePlanInfo>
<chargeRatePlanName>recurring charge</chargeRatePlanName>
<ratePlanIID>RatePlanID</ratePlanIID>
</chargeEventMap>For more information, see "About Prorating Recurring Charges and Rollovers".
Setting Full Day Proration
To configure full day proration in XML, you use the <validityRounding> and <scaleRounding> elements under the <ChargeOffering> element.
<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.
Set the <scaleRounding> element to one of the following:
- 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.
See "Configuring Timestamp Rounding" in BRM Configuring and Running Billing.
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"?>
<pdc:PricingObjectsJXB xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<ChargeOffering externalID="67a85a1b-a8af-45a4-8219-e22b085d4a3c">
<name>CO_OMS-9487</name>
<internalId>67a85a1b-a8af-45a4-8219-e22b085d4a3c</internalId>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>TelcoGsmTelephony</productSpecName>
<offerType>SUBSCRIPTION</offerType>
<priority>0</priority>
<partial>false</partial>
<purchaseMin>-1.0</purchaseMin>
<purchaseMax>-1.0</purchaseMax>
<ownMin>-1.0</ownMin>
<ownMax>-1.0</ownMax>
<applicableQuantity>REMAINING</applicableQuantity>
<purchaseCycleDOM>0</purchaseCycleDOM>
<expiryNotification>true</expiryNotification>
<subscriptionDueNotification>true</subscriptionDueNotification>
<dateRangeImpactType>EVENT_DATE</dateRangeImpactType>
<groupSharingEnabled>false</groupSharingEnabled>
<validityRounding>ON</validityRounding>
<scaleRounding>ON</scaleRounding>
<chargeEventMap>
<eventName>EventBillingProductFeeCycleCycle_forward_monthly</eventName>
<validIfCancelled>true</validIfCancelled>
<validIfInactive>true</validIfInactive>
<validIfSuspendedActive>true</validIfSuspendedActive>
<timezoneMode>EVENT</timezoneMode>
<minQuantity>0</minQuantity>
<minQuantityUnit>none</minQuantityUnit>
<incrementQuantity>1</incrementQuantity>
<incrementQuantityUnit>none</incrementQuantityUnit>
<roundingMode>NEAREST</roundingMode>
<prorateFirst>FULL_CHARGE</prorateFirst>
<prorateLast>PRORATE_CHARGE</prorateLast>
<prorateCycle>PRORATE_CHARGE</prorateCycle>
<chargeRatePlanInfo>
<targetEngine>RRE</targetEngine>
</chargeRatePlanInfo>
<chargeRatePlanName>CRP OMS-9487</chargeRatePlanName>
<ratePlanIID>5732f8f7-c46d-4fae-aa9a-3d1d5fcf41f7</ratePlanIID>
</chargeEventMap>
</ChargeOffering>
</pdc:PricingObjectsJXB>
For more information, see "Configuring Full Day Proration".
Setting Taxation for Charges
When configuring charges in XML, you can specify the tax code to use for calculating taxes as well as when to apply taxes. You can also specify a tax selector to determine the appropriate tax code. To do so, set the following elements under <chargeRatePlan>:
If you are setting a specific tax code:
-
<taxCode>: Set this to the name of the tax code.
If you are using a tax selector:
- <taxSelectorName>: Set this to the name of a previously defined tax selector.
- <taxSelectorIID>: Set this to the internal ID of the tax selector.
In both cases:
-
<taxTime>: Specify when to apply taxes:
-
NONE: Do not apply taxes.
-
EVENT_TIME: Taxes are calculated when the event is rated, and they are added to the customer's account balance. This way, you always have an accurate reading of a customer's account balance at any time in the accounting cycle.
-
BILLING_TIME: Taxes are calculated when the bill is generated. Deferring tax calculation to the billing process reduces rounding errors because all events of the same type are calculated together. For example, taxes are calculated on the total amount of usage fees rather than on individual usage events.
-
DYNAMIC: Taxes are calculated at billing time using the tax rate at the time the event occurred. This provides the benefits of billing-time taxation while allowing you to change tax rates in the middle of a billing cycle. For example, assume a recurring charge's tax rate changes from 2% to 3% on May 15. If a billing cycle ends on May 30, BRM would use the 2% rate to calculate the charge's April 30 through May 14 taxes and the 3% rate to calculate the charge's May 15 through May 29 taxes.
-
For example, to apply the VAT tax code and calculate taxes at billing time, the XML input file would include the following:
<chargeRatePlan xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Sample Charge</name>
<pricingProfileName>Subscription</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<taxCode>VAT</taxCode>
<applicableRums>Occurrence</applicableRums>
<applicableQuantity>ORIGINAL</applicableQuantity>
<taxTime>BILLING_TIME</taxTime>
<todMode>START_TIME</todMode>
<applicableQtyTreatment>CONTINUOUS</applicableQtyTreatment>
<permittedName>TelcoGsmTelephony</permittedName>
<permittedType>PRODUCT</permittedType>
<eventName>EventBillingProductFeeCycleCycle_forward_monthly</eventName>
<cycleFeeFlag>1</cycleFeeFlag>
<billOffset>0</billOffset>
...
</chargeRatePlan>For example, to use the Sample_TAX_SELECTOR tax code selector and calculate taxes when the event is rated, the XML input file would include the following:
<chargeRatePlan xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>20220105 $10 Monthly Charge</name>
<description>$10 Monthly Charge</description>
<pricingProfileName>Subscription</pricingProfileName>
<obsolete>false</obsolete>
<taxSelectorName>Sample_TAX_SELECTOR</taxSelectorName>
<taxSelectorIID>52407cd9-30f6-44b7-8519-eca5ba196d55</taxSelectorIID>
<applicableRums>Occurrence</applicableRums>
<applicableQuantity>ORIGINAL</applicableQuantity>
<taxTime>EVENT_TIME</taxTime>
<todMode>START_TIME</todMode>
<applicableQtyTreatment>CONTINUOUS</applicableQtyTreatment>
<eventName>EventBillingProductFeeCycleCycle_forward_monthly</eventName>
<cycleFeeFlag>0</cycleFeeFlag>
<billOffset>0</billOffset>
. . .
</chargeRatePlan>Using a Tax Exemption Selector
When creating charge offers in XML, you can use the <taxExemptionSelector> field to define a tax exemption selector for the charge offer.
To define a tax exemption selector, provide the name of a previously defined tax exemption selector in the <taxExemptionSelector> field.
For example, to use the Sample TaxExemptionSelector tax exemption selector for a charge offer, the XML input file would include the following:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<pdc:PricingObjectsJXB xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<chargeOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>20230105 ChargeOffer - $10 Monthly Charge</name>
<description>The TelcoGprs offer charges $10 Monthly fee</description>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
. . .
<ownMin>-1.0</ownMin>
<ownMax>-1.0</ownMax>
<taxExemptionSelectorName>Sample TaxExemptionSelector</taxExemptionSelectorName>
<applicableQuantity>REMAINING</applicableQuantity>
<purchaseCycleDOM>0</purchaseCycleDOM>
. . .
</chargeOffering>
</pdc:PricingObjectsJXB>Sharing Products Automatically with Sharing Group Members
When creating charge offers in XML, you can specify whether the charge offer is automatically shared with all members of an automated product sharing group when it is purchased by the group's owner. To do so, you use the <groupSharingEnabled> element under the <chargeOffering> element.
Set the <groupSharingEnabled> element to one of the following:
-
true: The charge offer is automatically shared with all members of an automated product sharing group when it is purchased by the group's owner.
-
false: The charge offer is not automatically shared with members of an automated product sharing group.
The following XML example specifies to automatically share the co1 charge offer with members of an automated product sharing group:
<chargeOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing" externalID="ExternalID">
<name>co1</name>
<internalId>InternalID</internalId>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>Ip</productSpecName>
<offerType>SUBSCRIPTION</offerType>
<priority>0</priority>
<partial>false</partial>
<purchaseMin>-1.0</purchaseMin>
<purchaseMax>-1.0</purchaseMax>
<ownMin>-1.0</ownMin>
<ownMax>-1.0</ownMax>
<applicableQuantity>REMAINING</applicableQuantity>
<purchaseCycleDOM>0</purchaseCycleDOM>
<expiryNotification>true</expiryNotification>
<subscriptionDueNotification>true</subscriptionDueNotification>
<dateRangeImpactType>EVENT_DATE</dateRangeImpactType>
<groupSharingEnabled>true</groupSharingEnabled>
<validityRounding>NOT_SET</validityRounding>
<scaleRounding>OFF</scaleRounding>
<chargeEventMap>
<eventName>EventSession</eventName>
<validIfCancelled>true</validIfCancelled>
<validIfInactive>true</validIfInactive>
<validIfSuspendedActive>true</validIfSuspendedActive>
<timezoneMode>EVENT</timezoneMode>
<minQuantity>1</minQuantity>
<minQuantityUnit>none</minQuantityUnit>
<incrementQuantity>1</incrementQuantity>
<incrementQuantityUnit>none</incrementQuantityUnit>
<roundingMode>NEAREST</roundingMode>
<prorateFirst>PRORATE_CHARGE</prorateFirst>
<prorateLast>PRORATE_CHARGE</prorateLast>
<prorateCycle>PRORATE_CHARGE</prorateCycle>
<chargeRatePlanInfo>
<targetEngine>ECE</targetEngine>
</chargeRatePlanInfo>
... Using Date Ranges for Versioning
When creating charge offers in XML, you can add balance impacts with new date ranges to create new versions of the same charge offer.
You use the <dateRangeImpactType> field on charge offers to specify whether existing subscriptions move to the new balance impacts or continue with the old balance impacts.
BRM determines which balance impacts to apply based on the value of <dateRangeImpactType> as follows:
- EVENT_DATE: The charge event date determines which balance impacts are applied. Any existing subscriptions will use the new balance impacts after the existing date range ends. This is the default behavior.
- PURCHASE_DATE: The original purchase date determines which
balance impacts are applied. Any existing subscriptions will continue to use the old
balance impacts. Any new subscriptions purchased within the new date range will use
the new balance impacts.
Note:
If a customer transfers their subscription as part of a service group transfer and <dateRangeImpactType> is set to PURCHASE_DATE, the balance impacts will be determined based on the service transfer date, not the original purchase date. - INSTANTIATED_DATE: The original service instantiation date determines which balance impacts are applied. Any existing subscriptions will continue to use the old balance impacts. Any new subscriptions instantiated during the new date range will use the new balance impacts. 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 pricing, while those who purchase under the old pricing can take advantage of the new pricing if it comes into effect before their new service is available.
The following shows an example of a charge offer using <dateRangeImpactType>:
<ChargeOffering externalID="1234">
<name>Charge Offering With Purchase Date Impact</name>
<internalId>InternalID</internalId>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>TelcoGsmTelephony</productSpecName>
<dateRangeImpactType>PURCHASE_DATE</dateRangeImpactType>
<offerType>SUBSCRIPTION</offerType>
<priority>0</priority>
<partial>false</partial>
<purchaseMin>-1.0</purchaseMin>
<purchaseMax>-1.0</purchaseMax>
<ownMin>-1.0</ownMin>
<ownMax>-1.0</ownMax>
<applicableQuantity>REMAINING</applicableQuantity>
<chargeEventMap>
...
</chargeEventMap>
</ChargeOffering>The following examples describe how the value of <dateRangeImpactType> effects the balance impacts applied. In the examples, you have an existing charge offer with a charge with a credit balance impact 1GB of free data every week. You add a new balance impact crediting 1.5GB, set the end date of the old balance impact to June 10th, and set the start date for the new balance impact to June 11th. Depending on the value of <dateRangeImpactType> for the charge offer, the following happens:
- If <dateRangeImpactType> is set to EVENT_DATE, all subscriptions get 1GB until June 10th, and 1.5GB thereafter.
- If <dateRangeImpactType> is set to PURCHASE_DATE, subscriptions purchased before June 10th continue to get 1GB, even for events occurring after June 10th. Subscriptions purchased after June 10th get 1.5GB.
- If <dateRangeImpactType> is set to INSTANTIATED_DATE, subscriptions instantiated before June 10th continue to get 1GB, even for events occurring after June 10th. Subscriptions instantiated after June 10th get 1.5GB, even if they were purchased before.
Discount Offer Configuration Examples
To configure discount offer functionality by using the PDC XML Pricing Interface, see the following examples:
Consuming Noncurrency Resources for Discounts in Order of Expiration
When creating discount offers in XML for rating in Oracle Communications Billing and Revenue Management Elastic Charging Engine (ECE), you can specify whether to consume noncurrency resources for the discounts in order of earliest expiry, or in order of any discount rules configured.
To do so, set the <resourcesConsumptionOrder> element under the discount (alterationRatePlan) to one of the following:
- EARLIEST_EXPIRY: Consume noncurrency resources according to which resource expires first. For example, if the customer is subscribed to one discount that grants minutes that expire monthly and another that grants minutes that expire yearly, the minutes expiring monthly should be consumed first. If all resources have the same validity dates, the discount rule order will be used.
- RULE_ORDER: Consume balances according to the configured discount rules, without taking validity into account.
The following XML example specifies to consume noncurrency resources in order of earliest expiration.
<alterationRatePlan xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Consumption Order Example Discount</name>
<internalId>InternalID</internalId>
<pricingProfileName>Standard Discount ECE</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<taxCode>ct_direct</taxCode>
<resourcesConsumptionOrder>EARLIEST_EXPIRY</resourcesConsumptionOrder>
<arpDateRange>
<startDate>0</startDate>
<endDate>inf</endDate>
<alterationConfiguration>
<applicableChargeAndQuantity>REMAINING_CHARGE</applicableChargeAndQuantity>
<arpCompositePopModel>
<name>Pricing</name>
<alterationPopModel>
<priceTier>
<distributionMethod>FROM_BAL_IMPACT</distributionMethod>
<tierBasis>
<chargeTierExpression>
<useTierComponent>false</useTierComponent>
<preRated>false</preRated>
</chargeTierExpression>
</tierBasis>
<lowerBound>
<numberTBExpression>
<value>0</value>
</numberTBExpression>
</lowerBound>
<tierRange>
<upperBound>
<numberTBExpression>
<value>NO_MAX</value>
</numberTBExpression>
</upperBound>
<percentAlteration>
<price>-0.11</price>
<unitOfMeasure>NONE</unitOfMeasure>
<balanceElementNumCode>840</balanceElementNumCode>
<alterationAppliesTo>USER</alterationAppliesTo>
<alterationBasedOn>
<chargeBasisExpression>
<useTierComponent>false</useTierComponent>
<preRated>false</preRated>
</chargeBasisExpression>
</alterationBasedOn>
<priceType>GRANT</priceType>
<priceValidity>
<startValidityMode>IMMEDIATE</startValidityMode>
<endValidityMode>NEVER</endValidityMode>
<validityRange>0/inf</validityRange>
<relativeStartOffset>-1</relativeStartOffset>
<relativeEndOffset>-1</relativeEndOffset>
</priceValidity>
</percentAlteration>
</tierRange>
</priceTier>
</alterationPopModel>
</arpCompositePopModel>
</alterationConfiguration>
</arpDateRange>
</alterationRatePlan>Sharing Discount Offers Automatically with Sharing Group Members
When creating discount offers in XML, you can specify whether the discount offer is automatically shared with all members of an automated discount offer sharing group when it is purchased by the group's owner. To do so, you use the <groupSharingEnabled> element under the <alterationOffering> element.
Set the <groupSharingEnabled> element to one of the following:
-
true: The discount offer is shared with all members of an automated discount offer sharing group when it is purchased by the group's owner.
-
false: The discount offer is not shared with members of an automated discount offer sharing group.
The following XML example specifies to automatically share the do1 discount offer with members of an automated discount offer sharing group:
<alterationOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing" externalID="ExternalID">
<name>do1</name>
<internalId>InternalID</internalId>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<timeRange>0/inf</timeRange>
<productSpecName>Ip</productSpecName>
<offerType>SUBSCRIPTION</offerType>
<priority>0</priority>
<purchaseMin>-1.0</purchaseMin>
<purchaseMax>-1.0</purchaseMax>
<ownMin>-1.0</ownMin>
<ownMax>-1.0</ownMax>
<applicableChargeAndQuantity>REMAINING_CHARGE</applicableChargeAndQuantity>
<groupSharingEnabled>true</groupSharingEnabled>
...Using a Tax Selector
You can specify a tax selector for both a subscription and for a convergent pricing profile (for ECE).
You can specify the tax selector for a subscription at both the discount (alterationRatePlan) level and the tierRange level. In both cases, you use the <taxSelectorName> parameter to set the tax selector.
For example, to use the Sample_TAX_SELECTOR tax selector for a subscription discount and the Sample_TAX_SELECTOR_2 tax selector for a tierRange, the XML input file would include the following:
<alterationRatePlan xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>20230302-0855 DiscountRatePlan</name>
<pricingProfileName>Subscription Discount</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<taxSelectorName>Sample_TAX_SELECTOR</taxSelectorName>
<arpDateRange>
<startDate>0</startDate>
<endDate>inf</endDate>
<alterationConfiguration>
<applicableChargeAndQuantity>REMAINING_CHARGE</applicableChargeAndQuantity>
<arpCompositePopModel>
<name>Pricing</name>
<alterationPopModel>
<priceTier>
. . .
<tierRange>
. . .
<percentAlteration>
. . .
<priceType>CONSUMPTION</priceType>
<taxTime>EVENT_TIME</taxTime>
<taxSelectorName>Sample_TAX_SELECTOR_2</taxSelectorName>
</percentAlteration>
. . .
</tierRange>
</priceTier>
</alterationPopModel>
</arpCompositePopModel>
</alterationConfiguration>
</arpDateRange>
</alterationRatePlan>You specify the tax selector for a convergent pricing profile (for ECE) at the discount (alterationRatePlan) level using the <taxSelectorName> parameter.
For example, to use the Sample_TAX_SELECTOR tax selector for a convergent pricing profile discount, the XML input file would include the following:
<alterationRatePlan xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>20230227 - DiscountRatePlan</name>
<pricingProfileName>Standard Discount</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<taxSelectorName>Sample_TAX_SELECTOR</taxSelectorName>
<resourcesConsumptionOrder>RULE_ORDER</resourcesConsumptionOrder>
. . .
</alterationRatePlan>Package Configuration Examples
To configure package functionality by using the PDC XML Pricing Interface, see the following examples:
Activating Offers in Packages
When creating packages in XML, you can specify whether to activate all charge offers across all bundles in a package when one of the charge offers is activated on first usage. To do so, you use the <firstUsageActivation> element under the <package> element.
Set the <firstUsageActivation> element to one of the following:
-
true: Activates all charge offers in the package upon first usage of any charge offer in the package.
For example, assume a package contains bundle 1 with charge offers A and B, and bundle 2 with charge offer C. If the first service a customer uses is in charge offer B, all charge offers (A, B, and C) are activated at that time.
-
false: When one charge offer in the package is activated on first usage, only that charge offer is activated. The other charge offers are not affected.
For example, assume a package contains bundle 1 with charge offers A and B, and bundle 2 with charge offer C. If the first service a customer uses is in charge offer B, only charge offer B is activated at that time. This is the default.
The following shows an example of a package with the <firstUsageActivation> element set:
<package xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>PackageWithPSCAttributes</name>
<internalId>InternalID</internalId>
<pricingProfileName>Subscription</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<billOnPurchase>false</billOnPurchase>
<firstUsageActivation>true</firstUsageActivation>
<productSpecPackageItem>
<name>TelcoGsmTelephony</name>
<balanceSpecificationName>Account Balance Group</balanceSpecificationName>
<productSpecName>TelcoGsmTelephony</productSpecName>
<bundledProductOfferingAssociation>
<optional>false</optional>
<cancelWithService>false</cancelWithService>
<bundledProductOfferingName>bundleForPkg</bundledProductOfferingName>
</bundledProductOfferingAssociation>
</productSpecPackageItem>
<balanceSpecification>
<name>Account Balance Group</name>
</balanceSpecification>
</package>Setting Loan Thresholds for Packages
When creating balance credit profiles for packages in XML, you can use the following types in <thresholdLevel> elements to set balance thresholds below which a customer is offered a loan:
- PERCENTAGE_LOAN: When this percent of the balance is consumed, the customer is offered a loan. The percentage must be in 5% increments.
- ABSOLUTE_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, each contained within a separate <thresholdLevel> element.
When the customer subscribes to the package, 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 types. The PERCENTAGE_LOAN and ABSOLUTE_LOAN types are used for offering loans, and the PERCENTAGE and ABSOLUTE types are used for different notifications or automatic top-ups:
<package>
<name>Package for Loan Thresholds</name>
<internalId>InternalID</internalId>
<pricingProfileName>Subscription</pricingProfileName>
<priceListName>Default Price List</priceListName>
<obsolete>false</obsolete>
<billOnPurchase>false</billOnPurchase>
<productSpecPackageItem>
<name>TelcoGsmTelephony</name>
<balanceSpecificationName>Account Balance Group</balanceSpecificationName>
<productSpecName>TelcoGsmTelephony</productSpecName>
<bundledProductOfferingAssociation>
<optional>false</optional>
<cancelWithService>false</cancelWithService>
<bundledProductOfferingName>Bundle for Voice</bundledProductOfferingName>
</bundledProductOfferingAssociation>
</productSpecPackageItem>
<balanceSpecification>
<name>Account Balance Group</name>
<balanceElementSpecification>
<balanceElementNumCode>840</balanceElementNumCode>
<consumptionRule>EARLIEST_EXPIRATION</consumptionRule>
<balanceCreditProfile>
<floor>10.0</floor>
<ceiling>100.0</ceiling>
<thresholdLevel>
<threshold>90.0</threshold>
<type>PERCENTAGE</type>
</thresholdLevel>
<thresholdLevel>
<threshold>25.0</threshold>
<type>ABSOLUTE</type>
</thresholdLevel>
<thresholdLevel>
<threshold>95.0</threshold>
<type>PERCENTAGE_LOAN</type>
</thresholdLevel>
<thresholdLevel>
<threshold>5.0</threshold>
<type>ABSOLUTE_LOAN</type>
</thresholdLevel>
</balanceCreditProfile>
</balanceElementSpecification>
</balanceSpecification>
</package>Transitioning Packages
When creating package transitions in XML, you can configure how PDC applies charges when customers transition packages in the middle of their billing cycle by using the <prorationType> element under the <packageTransition> element.
Set the <prorationType> element to one of the following:
-
PRORATE_CHARGE: Specifies to prorate charges for both packages. This is the default.
-
ORIGINAL_CHARGE: Specifies to apply the full charges from the original package.
-
TRANSFER_CHARGE: Specifies to apply the full charges from the new package.
The following shows an example that applies the full charge from the original package when the package is transitioned in the middle of a billing cycle:
<packageTransition xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>sample package transition</name>
<internalId>InternalID</internalId>
<pricingProfileName>Subscription</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<active>true</active>
<timeRange>0/inf</timeRange>
<waivePurchaseFee>true</waivePurchaseFee>
<waiveCancelFee>true</waiveCancelFee>
<productSpecName>TelcoGsmTelephony</productSpecName>
<prorationType>ORIGINAL_CHARGE</prorationType>
<type>UPGRADE</type>
<fromPackageName>Package A</fromPackageName>
<toPackageName>Package B</toPackageName>
</packageTransition>Selector Configuration Examples
To configure selector functionality by using the PDC XML Pricing Interface, see the following examples:
Configuring Tax Selectors
You can configure tax selectors, which are used to apply different tax codes based on the value of one or more service, event, profile, or customer attributes. You do this using the <taxSelector> element.
The following shows an example of a <taxSelector> element:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><pdc:PricingObjectsJXB xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<taxSelector xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Sample_TAX_SELECTOR</name>
<description>Sample TAX_SELECTOR</description>
<pricingProfileName>Convergent Usage</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<stereoType>TAX_SELECTOR</stereoType>
<productSpecName>TelcoGsmSms</productSpecName>
<eventSpecName>EventDelayedSessionTelcoGsm</eventSpecName>
<validityPeriod>
<validFrom>0</validFrom>
<rule>
<name>Rule1</name>
<result>
<resultName>VAT</resultName>
</result>
<fieldToValueExpression>
<operation>REGEX</operation>
<seperator>;</seperator>
<fieldName>EventDelayedSessionTelcoGsm.CALLED_ID</fieldName>
<fieldValue>1800.*</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
</rule>
<rule>
<name>Rule2</name>
<result>
<resultName>toll</resultName>
</result>
<fieldToValueExpression>
<operation>REGEX</operation>
<seperator>;</seperator>
<fieldName>EventDelayedSessionTelcoGsm.CALLED_ID</fieldName>
<fieldValue>.*</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
</rule>
</validityPeriod>
</taxSelector></pdc:PricingObjectsJXB>
Configuring Tax Exemption Selectors
You can configure tax exemption selectors, which are used to apply different tax exemptions based on the value of one or more service, event, profile, or customer attributes. You do this using the <taxExemptionSelector> element.
The following shows an example of a <taxExemptionSelector> element:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<pdc:PricingObjectsJXB xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<taxExemptionSelector xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<name>Sample TaxExemptionSelector</name>
<description>Sample TaxExemptionSelector</description>
<pricingProfileName>Product Offering</pricingProfileName>
<priceListName>Default</priceListName>
<obsolete>false</obsolete>
<stereoType>TAX_EXEMPTION_SELECTOR</stereoType>
<productSpecName>TelcoGprs</productSpecName>
<eventSpecName>EventSessionTelcoGprs</eventSpecName>
<customerSpecName>Account</customerSpecName>
<validityPeriod>
<validFrom>0</validFrom>
<rule>
<name>TES_rule1</name>
<result>
<resultName>USATaxExemptionCode</resultName>
</result>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>TelcoGprs.GPRS_INFO.ROUTING_AREA</fieldName>
<fieldValue>National</fieldValue>
<fieldKind>PRODUCT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>EventSessionTelcoGprs.TELCO_INFO.PRIMARY_MSID</fieldName>
<fieldValue>PMSID10248112193</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>IN_LIST</operation>
<seperator>;</seperator>
<fieldName>EventBillingProductFeeCycleCycle_forward_monthly.CYCLE_INFO.CYCLE_START_T</fieldName>
<fieldValue>20100101</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>IN_LIST</operation>
<seperator>;</seperator>
<fieldName>EventBillingProductFeeCycleCycle_forward_monthly.CYCLE_INFO.CYCLE_END_T</fieldName>
<fieldValue>20301231</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>AnyEvent.USAGE_TYPE</fieldName>
<fieldValue>Downlink</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>Account.ACCOUNT_NO</fieldName>
<fieldValue>ID12221521</fieldValue>
<fieldKind>CUSTOMER_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
</rule>
<rule>
<name>TES_rule2</name>
<result>
<resultName>IndiaTaxExemptionCode</resultName>
</result>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>TelcoGprs.GPRS_INFO.ROUTING_AREA</fieldName>
<fieldValue>SouthWest</fieldValue>
<fieldKind>PRODUCT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>EventSessionTelcoGprs.TELCO_INFO.PRIMARY_MSID</fieldName>
<fieldValue>PMSID10265018152</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>IN_LIST</operation>
<seperator>;</seperator>
<fieldName>EventBillingProductFeeCycleCycle_forward_monthly.CYCLE_INFO.CYCLE_START_T</fieldName>
<fieldValue>20200101</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>IN_LIST</operation>
<seperator>;</seperator>
<fieldName>EventBillingProductFeeCycleCycle_forward_monthly.CYCLE_INFO.CYCLE_END_T</fieldName>
<fieldValue>20321231</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>AnyEvent.USAGE_TYPE</fieldName>
<fieldValue>Uplink</fieldValue>
<fieldKind>EVENT_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
<fieldToValueExpression>
<operation>EQUAL_TO</operation>
<seperator>;</seperator>
<fieldName>Account.ACCOUNT_NO</fieldName>
<fieldValue>ID22220531</fieldValue>
<fieldKind>CUSTOMER_SPEC_FIELD</fieldKind>
</fieldToValueExpression>
</rule>
</validityPeriod>
</taxExemptionSelector>
</pdc:PricingObjectsJXB>