Skip to main content
Aria Knowledge Central

get_usage_history_m Guide

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.

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:

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.

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>).

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.

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.
Allowable Values
Values Description
true Discarded usage records will be included
false Discarded usage records will not be included
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
Allowable Values
Values Description
true Usage record has been excluded from billing.
false Usage record has not been excluded from billing.
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)

  • <tax_authority_level>
Allowable Values
Values Description
0 Federal
1 State/Province
2 County
3 City
4 Unincorporated Area
5 District

<usage_record_tax_details> (array)

  • <is_excluded>
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

1001: unexpected error


1004: authentication error

Associated Inputs: auth_key, client_id, client_no

<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)

Associated Inputs: acct_no, account_no, client_acct_id, user_id, userid, parent_acct_no

<acct_no>, <client_acct_id>

20003: Invalid Usage Type

Associated Inputs: specified_usage_type_no


20004: Invalid Usage Type Code

Associated Inputs: specified_usage_type_code


20007: Limit Records number must be greater than zero

Associated Inputs: Limit, limit_records


20013: Skip Records number must be greater than zero

Associated Input: offset


1016: invalid input, acct_no: (acct_no) is not a valid long, assignment_directive: (assignment_directive) is not a valid long, “billing_group_no: (billing_group_no) is not a valid long, threshold_billing_rule_no: (threshold_billing_rule_no) is not a valid long

Associated Inputs: alt_service_no_to_apply, assignment_directive, auto_skip_to_next_bill_date, client_billing_group_id, custom_rate_service_no/custom_rate_client_service_id, plan_instance_no, plan_instance_service_no, client_plan_instance_id, client_plan_instance_service_id, plan_instance_no, plan_instance_service_no, client_plan_instance_id, client_plan_instance_service_id, plan_instance_service_no, eligible_plan_no, eligible_service_no, email, force_master_bill_date_reset, fulfillment_only, include_master_plans, include_supp_plans, include_billing_groups, include_payment_methods, include_master_plans, include_supp_plans, include_billing_groups, include_payment_methods, invoice_no, length_months, end_date, limit, limit_records, modify_directive, contract_plan_instances_update, modify_directive, contract_plan_instances_update, offset, percent_amount, percent_eval_plan_instance_no, client_percent_eval_plan_instance_id, percent_eval_service_no, client_percent_eval_service_id, phone_ext, work_phone_ext, plan_unit_inst_status_cd, plan_units, reason_code, start_date, end_date, start_date, end_date, status_cd, acct_no, assignment_directive, billing_group_no, threshold_billing_rule_no

Additional Comments:  This error can be caused by the wrong type of input, for example, text in a numbers-only field, an  or specifying a value other than one of the documented allowable values.

  • For the get_order_m API, this is the error code returned when the user passes an invalid order value for the <status_filter_cd> input which is other than the allowed values (0/null, 1, 2, 3, 4 and 5).
  • For the bulk_cancel_order_m API, invalid input can occur with the <order_status_directive> argument. Allowed values are 0, 1, 2, 3, 4/null, 5 and 6.
  • For the get_acct_coupon_details_m API, invalid input can occur with the <include_all_active> input parameter (values are 0, 1 or NULL).

Alternate Message Output

1016: username cannot be longer than 30 characters
1016: first_name cannot be longer than 30 characters
1016: last_name cannot be longer than 30 characters

Associated APIs: create_user_m, update_user_m

Associated Inputs: username, first_name, last_name

<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

Associated Input: invoice_line_item

Additional Comments: Invoice_no is required if invoice_line_item is specified


1033:  a parameter that represents a true or false value contains invalid input

Associated Inputs: alt_collect_on_approve, alt_send_statement_on_approve, cancel_orders_on_discard, cascade_action, do_auto_discard, do_collect, change_status_after_coll, reset_dates_after_status, disable_existing_on_update, do_write, exclude_terminated_plan_inst, include_all_rate_schedules, include_plan_hierarchy, retrieve_bundled_nso, retrieve_included_nso, include_translations, include_inactive_items, include_invoice_activity_eligibility, include_rs_summary, include_translations, include_service_supp_fields/include_product_fields/, include_plan_instance_fields/include_plan_services/, include_surcharges, include_void_transactions, include_voided, invoice_unbilled_usage, is_unlinked_refund, record_cc_on_auth_failure, retrieve_excluded_usage, send_email, usage_pooling, do_write


14071: Master Plan Instance information is missing

Associated Inputs: plan_instance_no, client_plan_instance_id, master_plan_instance_no, client_master_plan_instance_id

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

Associated Inputs: master_plan_instance_no


14054: Invalid client Master Plan Instance identifier

Associated Inputs: client_master_plan_instance_id


16012: Contract end date is less than start date

Associated Inputs: date_range_start, date_range_end, start_date, end_date, length_months

<date_range_start>, <date_range_end>

1067: Locale no does not exist in the system.

Associated Inputs: locale_no, master_plan_instance_no


1066: Locale name does not exist in the system.

Associated Inputs: locale_name

  • Was this article helpful?