4.5 Usage Activity API

Usage Activity records are used for metered billing and used in conjunction with a Plan that has one or more Usage based charges. 

4.5.1. Retrieve Usage Activity:

GET /rest/activities?format=xml

GET /rest/activities?format=xml&max=[x]&offset=[z]

GET /rest/activities?format=xml&extCustomerRef=[ref]

GET /rest/activities?format=xml&customerId=[id]

GET /rest/activities?format=xml&orderNumber=[n]

GET /rest/activities?format=xml&invoiceNumber=[z]

GET /rest/activities?format=xml&priceCode=[code]

GET /rest/activities?format=xml&beginDate=[yyyy-MM-dd]

GET /rest/activities?format=xml&beginDate=[yyyy-MM-dd]&endDate=[yyyy-MM-dd]

Notes

• 1. 1. The maximum number of Activity records that may be returned in a single call is 100. Quantities greater than this may be retrieved in batches by advancing the offset a page at a time.

     2. Any of the above querystring parameters may be combined to filter the results

     3. The "invoiceNumber" for the Activity is only assigned when it has been billed (i.e., Activity.status changes from 'Unbilled' to 'Processed'). Consequently this filter criteria can only be applied for billed activity records.

     4. The 'beginDate' and 'endDate' may be used to filter on the Activity.chargeDate.

Sample Output:

<list>

  <activity id="147">

    <activityBatch id="29" />

    <status>Unbilled</status>

    <chargeDate>2011-08-31</chargeDate>

    <customer id="316" />

    <amount />

    <order id="357" />

    <orderLineItem id="1154" />

    <dateCreated>2011-08-01</dateCreated>

    <extRefId>BL1-00002A</extRefId>

    <quantity>261.00</quantity>

    <chargeEndDate />

    <invoiceText />

    <unitPrice />

  </activity>

  <activity id="148">

  ...

  </activity>

</list>

4.5.2. Create (Upload) Usage Activity:

Usage activity may be uploaded as a batch (with a maximum of 1000 records ber batch).There are 3 critical fields that are required for all Activity records. It is recommend that your calling programs send all the 3 fields if they are available.

• 1. The Customer may be specified by either the internal (BluBilling) customer id or the external customer reference number. If the order id/number is specified, then the customer can be inferred and therefore left blank.

  2. The Order may be specified by either the order id or order number. See note #2 below for additional details, including the option to leave this blank. If the specified customer has only one active order (with order start and end dates that span the activity charge date), and this order contains the specified PriceCode, then this is automatically selected.

  3. The Order Line Item is usually specified by specifying the PriceCode (configured in the Charges associated with the Plan). If the specified Order has only one line item, then this is automatically selected.

The example shows both forms of specifying the required fields.

POST /rest/activities?format=xml

<list>

  <activity> <!-- Note this block uses external IDs -->

    <extRefId>A001</extRefId>

    <extCustomerRef>JOHNDOE001</extCustomerRef>

    <priceCode>STORAGE</priceCode>

    <orderNumber>1007</orderNumber>

    <quantity>10.00</quantity>

  </activity>

  <activity> <!-- Note this block uses internal (BluBilling assigned) IDs -->

    <extRefId>NW003</extRefId>

    <customer id="316" />

    <priceCode>NETWORK</priceCode>

    <order id="357" />

    <quantity>12.50</quantity>

  </activity>

</list>

Notes:

1. The <extRefId> may be used to assign a correlation id that uniquely identifies the record to your organization.

2. The algorithm for automatically determining the Customer, Order, and OrderLineItem fields is:

   1. • If only the Customer and PriceCode details are provided, but not the Order details, then find any order having this PriceCode that is in active status and having order start and end dates that span the activity charge date. If no orders or multiple orders are found with this criteria, then an error is returned.

      • If only the Order details are provided, and the Order has only one OrderLineIItem of type UsageCharge, then the system uses this one. If multiple Usage-based Charges (or none) are found, then an error is returned.

3. BluBilling will update the <status> to "Processed" and assign the correct <amount> when the billing process runs based on the pricing configuration. However, if you populate the amount, then this value will be used.

4. The <chargeDate> indicates the date on which the charge is incurred and used by the billing run to determine which charges to process for a given billing period. It defaults to the current date if not provided. 

5. You may verify that the usage activity has been uploaded correctly by logging into the system and using the "System >> Usage Activity" screen

4.5.3. Delete Individual Activity Records:

To delete a record (that has not yet been billed), use the HTTP DELETE call:

DELETE /rest/activity/id?format=xml

DELETE /rest/activity?format=xml&extRefId=[code]

Note that records must be deleted one at a time. The singular form of "activity" is used in the URL (rather than "activities").