Recording Rated Units

“Rated Units” are the means by which Subscribe measures the number of licenses or units of usage for which your customers are billed. Subscribe needs to be informed of the actual usage of your product. To enter customer usage for billing calculations, you must report Rated Units as Events through the Subscribe API. Rated Units are grouped into Events for reporting purposes. Each Event must be associated with a single AutoBillItem; but one AutoBillItem can have any number of Events. When Events are reported for usage-based plans, the events are stored as unbilled usage until the scheduled billing date, at which point they are aggregated and compared to the appropriate rate plan for rating and billing. Use the RatePlan.recordEvent method to pass an array of Events to your Subscribe system. If you wish to pass more than 50 Events, you must break your call into several separate Record calls. However, because each Event can have any Quantity, you can define an Event to be either the actual usage, or some group or period of usage. Note: Subscribe allows 50 Events to be reported through each Record call. Vindicia best practices recommendation is to use the recordEvent method to report batches of Events, at designated moments throughout the day. Each Event refers to exactly one AutoBillItem, and the Event object must identify the item that is intended. When reporting Events, be certain to identify a unique AutoBillItem for each Event. The AutoBillItem may be identified using any combination of the following objects’ identifiers: Account, AutoBill, AutoBillItem, or Product. Subscribe requires that at least one of the following three data members be specified: Account, AutoBill, or AutoBillItem. When reporting Events, Subscribe will issue an error if two AutoBillItems exist which fulfill the reported Event parameters. Be certain to pass in enough information to uniquely identify the AutoBillItem to which the Event should refer. The following example identifies the AutoBillItem directly.

Record a Rated Unit Event

$rateplan = new RatePlan;
$event = new Event;
 
$event->setMerchantEventId('rating_123');
$event->setMerchantAutoBillItemId('abitem_321');
$event->setAmount(42);
 
$response = $rateplan->recordEvent(array($event));

While the merchantEventId is optional, it may be used to guarantee that a single Event is not reported multiple times. If you report the same Event twice with the same identifier, Subscribe will reject the second reported Event. It is also useful in customer support, when searching for a questioned billing item. In the previous example, rating_123is used as an identifier for the Reported Event.

Record an Event for a specific AutoBill

The following example identifies the rated AutoBillItem by its MerchantAutoBillId. If there is only one AutoBillItem on the listed AutoBill, this method will uniquely identify the AutoBillItem. If there is more than one AutoBillItem on the AutoBill, Subscribe will return an error string saying the input AutoBillItem is not unique. Note: When working with Rate Plans, assign a name to AutoBillItems, to facilitate working with Events.

$rateplan = new RatePlan;
$event = new Event;
 
$event->setMerchantEventId('rating_124');
$event->setMerchantAutoBillId('ab_715');
$event->setAmount(42);
 
$response = $rateplan->recordEvent(array($event));
 

Record an Event for a specific AutoBill and Product

$rateplan = new RatePlan;
$event = new Event;
 
$event->setMerchantEventId('rating_125');
$event->setMerchantAutoBillId('ab_715');
$event->setMerchantProductId('pr_29');
$event->setAmount(42);
 
$response = $rateplan->recordEvent(array($event));

If there are multiple rated Products on an AutoBill, identifying both the AutoBill and the Product ID may uniquely identify the AutoBillItem associated with the Event. Parent topic:Working with Rate Plans

Home

Guides

APIs

Record a Rated Unit Event

Record an Event for a specific AutoBill

Record an Event for a specific AutoBill and Product

​Record a Rated Unit Event

​Record an Event for a specific AutoBill

​Record an Event for a specific AutoBill and Product

Record a Rated Unit Event

Record an Event for a specific AutoBill

Record an Event for a specific AutoBill and Product