Any application that sells something needs to know the price of what is being sold. Many times this price is very straight forward, but in some cases it is not.
When you need to resolve a price that is not trivial, you will be better of using a pricing, or “rating”, engine. This engine will take into account a lot of different factors to price a product or service, such as:

• The date or time: is it cheaper on weekends or evenings? (like a cell phone plan)
• The presence of other products in the shopping cart (“If you buy this product, you can also purchase that product at half price.”)
• Any discounts (“50% off in October!”)
• Taxes (calculating them can get tricky)

There are two key factors that allow jBilling to work as a rating engine. The first is that you can add pricing rules without changing code, it is very simple to add a “50% off in October” rule because jBilling uses JBoss rules to do pricing. The second one is the jBilling API that allows another system to ask jBilling at any time the price of a product, or group of them.

Let’s go over the various rating scenarios, and identify the method from the jBilling API that would help …

Single Product Price

If all you need is to price a single product, you can simply call ‘Get Item’:

api.getItem(Integer itemId, Integer userId, PricingFields[])

This will return an item that is priced. You can pass only the item ID, this is fine if the customer is not important for resolve the price. For example, a price rule that is ‘50% off for October’ will work with just the item ID, but if you want to do ‘50% for Peter’ then the user ID is needed. Pricing fields will also allow you to pass arbitrary data that will be made available to the rules engine to build conditions.

Multiple Product Price

What if your price is affected by the quantity or other items being purchased in this same transaction? For example: “Buy two, get the third one free”, or “buy one pair of shoes, get socks at half price”. For this, we need to be able to pass quantity and many items at the same time:

api.rateOrder(OrderWS order)

An order can have multiple lines, and each line has a quantity field. jBilling will return this order with the changes done by the rating plug-ins. If you pass one line with a quantity of 3, the system could change the price to the equivalent of 2 units, implementing then the “buy two, get the third one free”.
This type of call is useful too for calculating taxes. jBilling will call a tax engine (or resolve the taxes on its own through rules) and add these taxes as new lines in the returned order.

Product Price Based in Account Context

All good but, what if the price is affected by something the customer did in the past, like crossing a certain threshold that triggers a discount? Or the opposite, not meeting a volume commitment and getting a penalty?
This is common and easy to implement in jBilling. You don’t even need to use a different API method, rate Order will do. The only change is that you will be passing the user id in the order that this method takes as a parameter.
The magic is done in the rating plug-ins. If using a rules based plug-in, then you can check any historical data that a customer has to alter the price. This also works for checking if the customer is of one type or another, subscribed to a specific plan or not.

Pricing an Event

If your application knows what the user is buying then all of the above apply, but it can be that the application does not know. For example, an event can happen of a customer doing something, like placing a phone call, and the application can not really tell what product this is involving.

The billing system needs to first resolve what this even means: in the example a call can be a call to a voice mail (price zero) a local call (maybe price zero, but if is a mobile phone things can change), a long distance call or an international call (prize definitely not zero). This product resolution and pricing can get complicated fast.

What we need here is real-time mediation. This is covered in detail in the telecom and integration guides. The main API method you need to work with is ‘Validate Purchase’. It will tell you how many of whatever the event translates to the customer can buy, given their current balance or credit limits. For this, the system will mediate the event first, by determining which product or products are being bought with this event, and then rate the products.