Home > Aria Crescendo Documentation > Aria Crescendo core api > get_usage_history_m

get_usage_history_m

This API returns usage records for an account, and can be filtered by date range, usage type, invoice, exclude status, and qualifiers. Using limit and offset inputs, results can be paginated. The fields "locale_no" and "locale_name" can be specified to translate output fields for which translations have been assigned to locales configured in Aria.

For information on error messages generated by this API, see get_usage_history_m Error Messages.

Input Arguments

Req Field Name Field Type Max Length Description
required-icon.png client_no long 22 Aria-assigned unique identifier indicating the Aria client providing service to this account.
required-icon.png auth_key string 32 Aria-assigned unique key to be passed with each method call for authenticating the validity of the requestor.
required-icon.png acct_no long 22 Aria-assigned account identifier. This value is unique across all Aria-managed accounts.
  OR      
  client_acct_id string 50 Client-defined account identifier.
required-icon.png master_plan_instance_no long 22

You can:

  1. Pass in the Aria-assigned unique identifier for the master plan instance (MPI) to get the usage history of only that MPI; or
  2. Pass in -1 to get the usage history of all MPIs for the specified account.
  OR      
  client_master_plan_instance_id string 100 Client-defined master plan instance ID.
  specified_usage_type_no long 8

The Aria-assigned usage type number to use when searching for usage history records.

You can pass in:

  • a <specified_usage_type_no> or <specified_usage_type_code> without a <date_range_start> or  <invoice_no>; or
  • a combination of (<specified_usage_type_no> or <specified_usage_type_code>) and/or (<date_range_start> and <date_range_end>) and (<invoice_no>).
  OR      
  specified_usage_type_code string 30

Optional client-defined usage type code.

You can pass in:

  • a <specified_usage_type_no> or <specified_usage_type_code> without a <date_range_start> or  <invoice_no>; or
  • a combination of (<specified_usage_type_no> or <specified_usage_type_code>) and/or (<date_range_start> and <date_range_end>) and (<invoice_no>).
  date_range_start string 19

The start-date of the given date range in yyyy-mm-dd hh24:mi:ss format. Timestamp is optional and will default to 00:00 hrs.

Note: A date_range_start is required if an invoice_no is not specified.
  date_range_end string 19 The end-date of the given date range in yyyy-mm-dd hh24:mi:ss format. Timestamp is optional and will default to 23:59:59 hrs.
  usage_qualifier_1 string array 300 Optional list of filters to apply against usage qualifier number 1, stored in the Aria system
  usage_qualifier_2 string array 300 Optional list of filters to apply against usage qualifier number 2, stored in the Aria system
  usage_qualifier_3 string array 300 Optional list of filters to apply against usage qualifier number 3, stored in the Aria system
  usage_qualifier_4 string array 300 Optional list of filters to apply against usage qualifier number 4, stored in the Aria system
  limit long 10 Limits the number of records returned by the API.
  offset long 10 The number of records to skip.
  invoice_no long 22

The Aria-assigned identifier for the invoice for which you are retrieving data.

You can pass in:

  • a <specified_usage_type_no> or <specified_usage_type_code> without a <date_range_start> or  <invoice_no>; or
  • a combination of (<specified_usage_type_no> or <specified_usage_type_code>) and/or (<date_range_start> and <date_range_end>) and (<invoice_no>).
Note: An invoice number is required if  date_range_start is not specified or if you are entering an invoice_line_item.
  invoice_line_item long 22

Returns all of the usage records with a usage type that matches that of the invoice line item specified.

Note: The invoice_no input is required if you are entering an invoice_line_item.
  retrieve_excluded_usage string 5 Use this field to include usage records that have been permanently excluded from billing   Allowable Values
  locale_no long 22 Aria-assigned unique identifier of the locale used for translations. This value must be unique across all Aria clients.
  OR      
  locale_name string 50 Name of the locale.
  alt_caller_id string 30 Person or process that submitted the API call. This can be someone's user ID, or the name of an application.
Start of <optional_transaction_qualifiers> array
  optional_transaction_qualifiers array   Array of additional values you can associate with this API call.
  brd_arrow.gif qualifier_name string 100 Name of the field you want to associate with this API call.
  brd_arrow.gif qualifier_value string 100 Corresponding value of the field you want to associate with this API call.
End of <optional_transaction_qualifiers> array
  client_record_id string 50 Client-defined identifier for a usage record.

Output Arguments

Field Name Field Type Description
error_code long Aria-assigned error identifier. 0 indicates no error.
error_msg string Description of any error that occurred. "OK" if there was no error.
usage_history_recs hash A multidimensional array of usage history records attached to the account (and optional specified usage type) for given date range
brd_arrow.gif billable_acct_no long Aria-assigned unique account identifier of the account who was billed the usage
brd_arrow.gif incurring_acct_no long Aria-assigned unique account identifier of the account that incurred the usage.
brd_arrow.gif client_billable_acct_id string This is the client-assigned identifier of the account who was billed the usage
brd_arrow.gif client_incurring_acct_id string This is the client-assigned identifier of the account that incurred the usage.
brd_arrow.gif plan_instance_id long The Subscription plan instance number.
brd_arrow.gif client_plan_instance_id string Client-defined plan Subscription plan instance ID.
brd_arrow.gif usage_type_no long Aria-assigned unique identifier representing the type of usage that is being recorded.
brd_arrow.gif usage_type_description string The name of this usage type used on all reports, account statements, etc., E.g. International Call Minutes
brd_arrow.gif usage_date string The date on which the given usage was incurred.
brd_arrow.gif usage_time string The time on which the given usage was incurred.
brd_arrow.gif units double The number of units incurred by the account holder.
brd_arrow.gif units_description string The name used for the unit type with which this usage type is metered, E.g. minutes
brd_arrow.gif usage_units_description string The name used for the unit type with which this usage type is metered, E.g. minutes
brd_arrow.gif invoice_no long The Aria-assigned ID corresponding to the invoice upon which this usage record was billed to the account holder.
brd_arrow.gif telco_to string The unconstrained string identifying the "sender" of the message represented by this usage record. Intended for usage records that represent a telecom-based form of usage whereby the sender/originator and the recipient/terminator of the message/usage record are desired to be recorded as notational-only elements (e.g. a phone call whereby the "from" telephone number and the "to" telephone number are desired as notational elements).
brd_arrow.gif telco_from string The unconstrained string identifying the "recipient" of the message represented by this usage record. Intended for usage records that represent a telecom-based form of usage whereby the sender/originator and the recipient/terminator of the message/usage record are desired to be recorded as notational-only elements (e.g. a phone call whereby the "from" telephone number and the "to" telephone number are desired as notational elements).
brd_arrow.gif specific_record_charge_amount double If the usage record was supplied to Aria in a pre-rated form, i.e. with a specified currency value already associated with it, the value originally supplied. NOTE: Most usage records are subject to end-of-period aggregate value determination and will not have a value here.
brd_arrow.gif is_excluded string Specifies whether or not the given usage record was entirely and permanently excluded from any billing (invoicing) process.   Allowable Values
brd_arrow.gif exclusion_comments string Comments entered to explain why the record was excluded from billing. Only recorded if is_excluded is true.
brd_arrow.gif comments string Comments entered while recording usage
brd_arrow.gif pre_rated_rate double Rate entered while recording usage
brd_arrow.gif qualifier_1 string The value of client-defined usage qualifier 1 for this usage record
brd_arrow.gif qualifier_2 string The value of client-defined usage qualifier 3 for this usage record
brd_arrow.gif qualifier_3 string The value of client-defined usage qualifier 3 for this usage record
brd_arrow.gif qualifier_4 string The value of client-defined usage qualifier 4 for this usage record
brd_arrow.gif recorded_units double The number of units recorded by the account holder.
brd_arrow.gif usage_rec_no long Aria-assigned usage record identifier.
brd_arrow.gif usage_parent_rec_no long Aria-assigned usage parent record identifier.
brd_arrow.gif usage_type_code string The usage type code of this record
brd_arrow.gif client_record_id string If available, the client-defined usage code for this usage record
brd_arrow.gif exclude_reason_cd long The reason why this usage record has been excluded from billing   Allowable Values
acct_locale_no long Aria-assigned unique identifier of the locale used for translations. This value is unique across all Aria-managed accounts.
acct_locale_name string Name of the account level locale.
Last modified

Tags

This page has no custom tags.

Classifications

This page has no classifications.
Powered by CXone Expert ®