The get_usage_history_m 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.
| API Specification: |
get_usage_history_m |
| Required Fields: |
- <client_no>
- <auth_key>
- <acct_no> or <client_acct_id>
- <master_plan_instance_no>
|
Additional Guidance
Input Fields
| Field Name |
Notes |
| <master_plan_instance_no> |
You can:
- Pass in the Aria-assigned unique identifier for the master plan instance (MPI) to get the usage history of only that MPI; or
- Pass in -1 to get the usage history of all MPIs for the specified account.
|
| <specified_usage_type_no> |
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>).
|
| <specified_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> |
A date_range_start is required if an invoice_no is not specified. |
| <invoice_no> |
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>).
An invoice number is required if date_range_start is not specified or if you are entering an invoice_line_item.
|
| <invoice_line_item> |
The invoice_no input is required if you are entering an invoice_line_item. |
| <retrieve_excluded_usage> |
Allowable Values
| Values |
Description |
| true |
Discarded usage records will be included |
| false |
Discarded usage records will not be included |
|
| <billed_filter> |
Allowable Values
| Values |
Description |
| 0 |
Return both billed and unbilled usage records. (Default) |
| 1 |
Billed usage records only |
| 2 |
Unbilled usage records only |
|
Output Fields
| Field Name |
Notes |
| <is_excluded> |
Allowable Values
| Values |
Description |
| true |
Usage record has been excluded from billing. |
| false |
Usage record has not been excluded from billing. |
|
| <exclude_reason_cd> |
Allowable Values
| Values |
Description |
| 1 |
No reason provided when discarding. |
| Any |
Random reason number given by client when discarding. |
|
|
<usage_history_recs> (array)
- <usage_record_pre_taxed_ind>
|
Allowable Values
| Values |
Description |
| 1 |
Client calculated taxes provided as input to Aria. |
| 2 |
Aria calculated taxes using Aria's internal tax method. |
|
|
<usage_history_recs> (array)
- <usage_record_tax_inclusive_ind>
|
Allowable Values
| Values |
Description |
| 0 |
Usage amount is Tax Exclusive. |
| 1 |
Usage amount is Tax Inclusive. |
|
|
<usage_record_tax_details> (array)
|
Allowable Values
| Values |
Description |
| 0 |
Federal |
| 1 |
State/Province |
| 2 |
County |
| 3 |
City |
| 4 |
Unincorporated Area |
| 5 |
District |
|
|
<usage_record_tax_details> (array)
|
Allowable Values
| Values |
Description |
| 0/null |
Tax record has not been excluded from billing. |
| 1 |
Tax record has been excluded from billing. |
|
Error Codes
| Error Code/Description |
Associated Inputs |
|
|
|
1004: authentication error
|
<auth_key>, <client_no> |
1009: account does not exist, Account not found: AriaNo (acct_no), Account not found: Userid (userid), or Account not found: ClientId (client_acct_id)
|
<acct_no>, <client_acct_id> |
20003: Invalid Usage Type
|
<specified_usage_type_no> |
20004: Invalid Usage Type Code
|
<specified_usage_type_code> |
20007: Limit Records number must be greater than zero
|
<limit> |
20013: Skip Records number must be greater than zero
|
<offset> |
1016: invalid input
Additional Comments: This error can be caused by the wrong type of input; for example, text in a numbers-only field, or specifying a value other than one of the documented allowable values.
|
<master_plan_instance_no>, <client_master_plan_instance_id>, <invoice_no>, <limit>, <offset>, <acct_no> |
3036: Invoice_line_item does not have qualifying invoice_no or transaction_no
Additional Comments: Invoice_no is required if invoice_line_item is specified
|
<invoice_line_item> |
1033: a parameter that represents a true or false value contains invalid input
|
<retrieve_excluded_usage> |
14071: Master Plan Instance information is missing
Additional Comments: Both plan_no and plan_id must be entered. Master Plan Instance is required if the invoice_no is not provided.
|
<master_plan_instance_no>, <client_master_plan_instance_id> |
14053: Invalid Master Plan Instance number
|
<master_plan_instance_no> |
14054: Invalid client Master Plan Instance identifier
|
<client_master_plan_instance_id> |
16012: Contract end date is less than start date
|
<date_range_start>, <date_range_end> |
1067: Locale no does not exist in the system.
|
<locale_no> |
1066: Locale name does not exist in the system.
|
<locale_name> |
