About the Billing Utilities

2 About the Billing Utilities

Learn about the main billing utilities in Oracle Communications Billing and Revenue Management (BRM), pin_bill_accts and pin_cycle_fees.

Topics in this document:

For information about all billing utilities, see "Billing Utilities".

Billing Accounts By Using the pin_bill_accts Utility

Use the pin_bill_accts utility to generate regular bills (not corrective bills).

The pin_bill_accts utility calculates the balance due for each account bill unit, and creates a bill for the balance due. It creates bills for accounts whose billing date is any day before midnight of the day that you run the pin_bill_accts utility as shown in Figure 2-1.

Figure 2-1 Accounts Included when Running pin_bill_accts

Description of "Figure 2-1 Accounts Included when Running pin_bill_accts"

The balance due amount is requested as a payment by the pin_collect utility, and is shown on the invoice.

The pin_bill_accts utility also performs the accounting cycle activity, such as creating new bill items.

For information about the pin_bill_accts utility syntax, see "pin_bill_accts".

When to Run the pin_bill_accts Utility

Use the pin_bill_day script to run the pin_bill_accts utility daily.

If you use bill unit hierarchies, you must run the pin_bill_accts utility to bill nonpaying child bill units before their paying parent bill units. The correct order is set in the pin_bill_day script.

You must run the pin_bill_accts utility before you run pin_collect because pin_collect needs the balance due amount collected by the pin_bill_accts utility.

About Bill Unit States and the pin_bill_accts Utility

The bill unit stores the state of a bill:

0 to indicate that the bill has been finalized.
1 to indicate that partial billing has been completed.
2 to indicate that all cycle charges and billing-time discounts have been applied at the end of the billing period and the bill needs to be finalized. A bill advances to this state only after billing is run for its account with the pin_bill_accts -cycle_charge_only parameter.

Running the pin_bill_accts utility with the -cycle_charge_only parameter runs billing on accounts with bill states 0 and 1. All cycle fees and billing-time discounts are applied, but totals are not calculated, and the bill is not finalized. At the end of the billing run, the bill state is set to 2.

To finalize a bill, run the pin_bill_accts utility with the -finalize_bill parameter. This runs billing on accounts with bill state 2. Totals are calculated, and items, bills, and so on are updated. At the end of the billing run, the bill state is set to 0.

Note:

These bill unit states, stored in the /billinfo object, are different from the informational bill states stored in the /bill object. See "About Bill States" in BRM Concepts for more information about bill-level states.

Using the pin_cycle_fees Utility

The pin_cycle_fees utility can perform the following tasks at the account level or the service level:

Apply charges for cycle-forward fees that have reached the end of free billing periods. For example, if a customer signs up for one month of free service, the pin_cycle_fees utility finds when the free period is over, and applies the cycle-forward fee balance impact to the customer's account balance group.
Cancel charge offers when a pending cancellation comes due. For example, if a charge offer is set to cancel at a future date, the pin_cycle_fees utility cancels the charge offer on that date.

Note:

You determine which of these two tasks pin_cycle_fees should perform by running it with different parameters.
Split charges for backdated operations. If the backdate window spans multiple event cycles, the utility splits the events for each cycle and applies the charges accordingly.

If a free period ends before the customer's billing date, the pin_cycle_fees utility calculates the prorated fees for the time between the end of the free period and the start of the customer's next accounting cycle.

For example, a customer opens an account on February 15 and is given one free month, but the customer's billing date is on the 1st of the month. When you run pin_cycle_fees on March 15, it finds that the customer's free time period has ended. The utility then assesses the prorated fee due for March 15 through March 31 and impacts the customer's balance with the prorated amount. The result is that the system makes no charges to the customer on March 1, but charges the prorated fee and the cycle fee on April 1 as shown in Figure 2-2.

Figure 2-2 Proration of Cycle Forward Fees by pin_cycle_fees

Description of "Figure 2-2 Proration of Cycle Forward Fees by pin_cycle_fees"

For information about the pin_cycle_fees utility syntax, see "pin_cycle_fees".

When to Run the pin_cycle_fees Utility

Use the pin_bill_day script to run the pin_cycle_fees utility daily. This applies the prorated balance impacts as soon as they are due. If you do not run the pin_cycle_fees utility daily, the pin_bill_accts utility applies the balance impacts for the expired cycle forward fees. The only difference is that the balance impacts are not calculated by the pin_cycle_fees utility on the day that the cycle-forward fee expires.

Improving Performance of the pin_cycle_fees Utility

If system performance slows unacceptably when running the pin_cycle_fees utility, edit the pin_bill_day script and change the default start and end parameters for the pin_cycle_fees utility to every other day or every third day.

Canceling an Account’s Charge Offer Using the pin_cycle_fees Utility

When you run pin_cycle_fees -defer_cancel to cancel products for a specified account, it internally calls PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT and then PCM_OP_SUBSCRIPTION_CYCLE_FORWARD, which cancels the account’s charge offers without applying cycle-forward fees to all other charge offers.

If you want BRM to apply cycle-forward fees to all charge offers before canceling an account’s charge offer, run pin_cycle_fees -regular_cycle_fees followed by pin_cycle_fees -defer_cancel.

Normally, pin_bill_day runs pin_cycle_fees -regular_cycle_fees followed by pin_cycle_fees -defer_cancel. If you run these utilities on days other than the billing day, you need to ensure that pin_cycle_fees -regular_cycle_fees is run first, followed by pin_cycle_fees -defer_cancel.

Processing a Subset of Accounts or Services Using XML Files

To run the pin_cycle_fees utility against a subset of account or services using an XML file:

(Optional) If you intend to process a subset of services, set the StagedBillingFeeProcessing business parameter is set to 1, 2, or 3. See "Applying Cycle Forward Fees in Parallel" in PDC Creating Product Offerings.
Create an XML file:
- For account-level processing, list the account POIDs in the following format:
```
<CycleFeeList>     
             <Account>12345</Account>
</CycleFeeList>
```
- For service-level processing, list the account and service POIDs in the following format:
```
<CycleFeeList>     
             <Account>12345</Account>     
             <Service>12345</Service>
</CycleFeeList>
```
Run the pin_cycle_fees utility with the -file filename.xml option. For example, to bill charge offers for a subset of accounts or services with a delayed purchase start time:
```
pin_cycle_fees -defer_purchase -file filename.xml
```

Processing a Subset of Accounts or Services Using Files in Flist Format

To run the pin_cycle_fees utility against a subset of account or services using a file in an flist format with a .txt extension:

(Optional) If you intend to process a subset of services, set the StagedBillingFeeProcessing business parameter is set to 1, 2, or 3. See "Applying Cycle Forward Fees in Parallel" in PDC Creating Product Offerings.

Create a TXT file in flist format:

For account-level processing, list the account POIDs in the following format:

0 PIN_FLD_RESULTS            ARRAY [0] allocated 20, used 9
1   PIN_FLD_POID              POID  [0] 0.0.0.1 /account 1808980
0 PIN_FLD_RESULTS            ARRAY [1] allocated 20, used 9
1   PIN_FLD_POID              POID  [0] 0.0.0.1 /account 203813 0

For service-level processing, list the account and service POIDs in the following format:

0 PIN_FLD_RESULTS              ARRAY [0] allocated20, used 9
1   PIN_FLD_POID                POID [0] 0.0.0.1 /account 180898 0
1   PIN_FLD_SERVICE_OBJ         POID [0] 0.0.0.1 /service/email 184226 0
0 PIN_FLD_RESULTS              ARRAY [1] allocated 20, used 9
1   PIN_FLD_POID                POID [0] 0.0.0.1 /account 203813 0
1   PIN_FLD_SERVICE_OBJ         POID [0] 0.0.0.1 /service/ip 201893 0

Run the pin_cycle_fees utility with the -f filename.txt option. For example, to charge cycle forward fees for a subset of accounts or services:
```
pin_cycle_fees -regular_cycle_fees -f filename.txt
```