Skip to main content
Aria Knowledge Central

get_usage_history_m

  1. Last updated
  2. Save as PDF

Summary

API Name get_usage_history_m
Class account_services_m
Update Version 57

Description

Retrieves individual usage records for a specified account. Each record represents a single usage event (recorded via record_usage_m or bulk_record_usage_m) with its type, units, date, billable units, amounts, qualifiers, and billing status. Results can be filtered by date range, usage type, invoice number, exclusion status, and qualifier values. Supports pagination via limit and offset parameters. Use locale_no or locale_name to return translated field values for multi-language environments. Use this for detailed usage analysis, usage dispute investigation, or customer-facing usage detail displays.

Inputs

Name Type Length Required Description
client_no long 22 Yes

Aria-assigned unique identifier indicating the Aria client providing service to this account.
auth_key string 32 No

Aria-assigned unique key for authenticating the validity of the requestor. This key is passed with each method call.
acct_no long 22 Yes

Aria-assigned account identifier. This value is unique across all Aria-managed accounts.

Alternative required field: client_acct_id
client_acct_id string 50 Yes

Client-defined account identifier.

Alternative required field: acct_no
master_plan_instance_no long 22 Yes

The Master Subscription plan instance number. If MPI is provided, then it will retrieve details sepecific to the MPI. If '-1' is provided, then it will retrieve all MPIs.

Alternative required field: client_master_plan_instance_id
client_master_plan_instance_id string 100 Yes

Client-defined Master plan Subscription plan instance ID.

Alternative required field: master_plan_instance_no
specified_usage_type_no long 8 No

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

Alternative field: specified_usage_type_code
date_range_start string 19 No

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.
date_range_end string 19 No

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

Optional client-defined usage type code

Alternative field: specified_usage_type_no
usage_qualifier_1 object   No

See fields below
usage_qualifier_2 object   No

See fields below
usage_qualifier_3 object   No

See fields below
usage_qualifier_4 object   No

See fields below
limit long 10 No

Limits the number of records returned by the API.
offset long 10 No

The number of records to skip.
invoice_no long   No

The Aria-assigned identifier for the invoice for which you are retrieving data. An invoice number is required if no date_range_start is specified.
invoice_line_item long 22 No

Returns all of the usage records with a usage type that matches that of the invoice line item specified. Note that the invoice_no input is required with invoice_line_item.
retrieve_excluded_usage string 5 No

Use this field to include usage records that have been permanently excluded from billing

Allowed values:

Value Description
True Discarded usage records will be included
False Discarded usage records will not be included
locale_no long 30 No

Aria-assigned unique identifier of the locale used for translations. This value must be unique across all Aria clients.

Alternative field: locale_name
locale_name string 100 No

Name of the locale.

Alternative field: locale_no
client_record_id string 100 No

Client-provided identifier for a given usage record.
billed_filter long 1 No

Specifies billed records or unbilled records

Allowed values:

Value Description
0 Return both billed and unbilled usage records. (Default)
1 Billed usage records only
2 Unbilled usage records only

usage_qualifier_1 fields

Name Type Length Required Description
usage_qualifier_1 string 300 No

Optional list of filters to apply against usage qualifier number 1, stored in the Aria system

usage_qualifier_2 fields

Name Type Length Required Description
usage_qualifier_2 string 300 No

Optional list of filters to apply against usage qualifier number 2, stored in the Aria system

usage_qualifier_3 fields

Name Type Length Required Description
usage_qualifier_3 string 300 No

Optional list of filters to apply against usage qualifier number 3, stored in the Aria system

usage_qualifier_4 fields

Name Type Length Required Description
usage_qualifier_4 string 300 No

Optional list of filters to apply against usage qualifier number 4, stored in the Aria system

Outputs

Name Type Length Required Description
error_code long   No

Aria-assigned error identifier. 0 indicates no error.
error_msg string   No

Description of any error that occurred. "OK" if there was no error.
usage_history_recs object   No

A multidimensional array of usage history records attached to the account (and optional specified usage type) for given date range

See fields below
acct_locale_no long 30 No

Aria-assigned unique identifier of the locale used for translations. This value is unique across all Aria-managed accounts.
acct_locale_name string 100 No

Name of the account level locale.
filtered_usage_count long   No

Total count of filtered usage records.
usage_record_tax_details object   No

Array of usage tax details

See fields below

usage_history_recs fields

Name Type Length Required Description
billable_acct_no long   No

Aria-assigned unique account identifier of the account who was billed the usage
incurring_acct_no long   No

Aria-assigned unique account identifier of the account that incurred the usage.
client_billable_acct_id string   No

This is the client-assigned identifier of the account who was billed the usage
client_incurring_acct_id string   No

This is the client-assigned identifier of the account that incurred the usage.
plan_instance_id long 22 No

The Subscription plan instance number.
client_plan_instance_id string 100 No

Client-defined plan Subscription plan instance ID.
usage_type_no long   No

Aria-assigned unique identifier representing the type of usage that is being recorded.
usage_type_description string   No

The name of this usage type used on all reports, account statements, etc., E.g. International Call Minutes
usage_date string   No

The date on which the given usage was incurred.
usage_time string   No

The time on which the given usage was incurred.
units double   No

The number of units incurred by the account holder.
units_description string   No

The name used for the unit type with which this usage type is metered, E.g. minutes
usage_units_description string   No

The name used for the unit type with which this usage type is metered, E.g. minutes
invoice_no long   No

The Aria-assigned ID corresponding to the invoice upon which this usage record was billed to the account holder.
telco_to string   No

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).
telco_from string   No

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).
specific_record_charge_amount double   No

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.
is_excluded string   No

Specifies whether or not the given usage record was entirely and permanently excluded from any billing (invoicing) process.

Allowed values:

Value Description
True Usage record has been excluded from billing.
False Usage record has not been excluded from billing.
exclusion_comments string   No

Comments entered to explain why the record was excluded from billing. Only recorded if is_excluded is true.
comments string   No

Comments entered while recording usage
pre_rated_rate double   No

Rate entered while recording usage
qualifier_1 string   No

The value of client-defined usage qualifier 1 for this usage record
qualifier_2 string   No

The value of client-defined usage qualifier 3 for this usage record
qualifier_3 string   No

The value of client-defined usage qualifier 3 for this usage record
qualifier_4 string   No

The value of client-defined usage qualifier 4 for this usage record
recorded_units double   No

The number of units recorded by the account holder.
usage_rec_no long   No

Aria-assigned usage record identifier.
usage_parent_rec_no long   No

Aria-assigned usage parent record identifier.
usage_type_code string   No

The usage type code of this record
client_record_id string   No

If available, the client-defined usage code for this usage record
exclude_reason_cd long   No

The reason why this usage record has been excluded from billing

Allowed values:

Value Description
1 No reason provided when discarding.
Any Random reason number given by client when discarding.
master_plan_instance_no long 22 No

The Master Subscription plan instance number.
client_master_plan_instance_id string 100 No

The client-defined identifier of the Master plan instance.
usage_record_pre_taxed_ind long   No

Flag to differentiate Client calculated and Aria calculated taxes.

Allowed values:

Value Description
1 Client calculated taxes provided as input to Aria.
2 Aria calculated taxes using Aria's internal tax method.
usage_record_tax_inclusive_ind long   No

This flag denotes if a rate is inclusive of the taxes. Value of 1 means tax inclusive rates and a value of 0 (default) means tax exclusive rates.

Allowed values:

Value Description
0 Usage amount is Tax Exclusive.
1 Usage amount is Tax Inclusive.

usage_record_tax_details fields

Name Type Length Required Description
usage_rec_no long   No

Aria-assigned usage record identifier.
tax_detail_line_no long   No

Line number associated with each tax detail record.
tax_amount double   No

Amount of tax applied for the given tax type.
tax_rate double   No

Rate at which tax is calculated for the tax type used by the tax engine.
taxable_amount double   No

Taxable amount of the tax type returned by the tax engine.
tax_jurisdiction_name string   No

Jurisdiction name returned by the tax engine.
tax_authority_level long   No

Tax jurisdiction code

Allowed values:

Value Description
0 Federal
1 State / Province
2 County
3 City
4 Unincorporated Area
5 District
tax_type_id string   No

Identifier of the tax type returned by the tax engine.
tax_type_desc string   No

Description of the tax type returned by the tax engine.
tax_category string   No

Category of the tax type returned by the tax engine.
tax_summary string   No

Summary text returned by the tax engine.
is_excluded long   No

Specifies whether or not this tax record is included for invoicing.

Allowed values:

Value Description
0/ null Tax record has not been excluded from billing.
1 Tax record has been excluded from billing.
TOP
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Page type
    Topic
  2. Tags
    This page has no tags.