Usages GET API Documentation

Purpose

The endpoint retrieves a list of usage records for metered charge items within the system. The API returns detailed usage data, including item information, usage quantity, time range, status, and pagination for navigating through large datasets.

Use Case

This endpoint is used by systems managing metered services, such as telecom or internet providers, to view customer usage details. For example, when a metered-type item is created and linked to an order, the system tracks the consumed minutes or data over a charging period, which can then be fetched for reporting, billing, or monitoring purposes.

Path Parameters

No request body is required for this endpoint.

Query Parameters

Parameter	Type	Description
limit	Integer	Number of records to return per request.
offset	Integer	Number of records to skip before starting to return results.

Request Body

No request body is required for this endpoint.

Response

The API endpoint returns a list of usage records containing UUID, version, associated charge item details, charging period, consumed quantity, unit of measure, start/end time, type, status, creation and update details, and any custom attributes. Also includes pagination details to navigate through multiple records.

                JSON
              

                      {
    "usages": [
        {
            "uuid": "UUID",
            "version": "VERSION",
            "charge_item_uuid": "UUID",
            "charge_item_name": "ITEM_NAME",
            "charging_period": "PERIOD_RANGE",
            "quantity": "NUMBER",
            "uom": "UNIT_OF_MEASURE",
            "start_time": "TIMESTAMP",
            "end_time": "TIMESTAMP",
            "type": "USAGE_TYPE",
            "charge_status": "STATUS",
            "source": "EMPTY",
            "created_by": "CREATED_BY",
            "created_on": "TIMESTAMP",
            "last_updated_by": "UPDATED_BY",
            "last_updated_on": "TIMESTAMP",
            "custom_attributes": [
                {
                    "name": "ATTRIBUTE_NAME",
                    "value": "EMPTY"
                }
            ]
        }
    ],
    "pagination": {
        "records": "NUMBER",
        "limit": "NUMBER",
        "offset": "NUMBER",
        "previous_page": "URL",
        "next_page": "URL"
    }
}
                    

Attribute	Type	Description
usages	Array	List of usage records.
uuid	String	Unique identifier of the usage record.
version	String	Version number of the record.
charge_item_uuid	String	UUID of the associated charge item.
charge_item_name	String	Name of the associated charge item.
charging_period	String	Period for which the usage is recorded.
quantity	String	Amount consumed.
uom	String	Unit of measurement (Minute, GB).
start_time	String	Start time of the usage tracking period.
end_time	String	End time of the usage tracking period.
type	String	Type of usage tracking (INCREMENTAL).
charge_status	String	Current status of the charge (ACTIVE).
source	String	Source of the usage record.
created_by	String	Name of the user who created the record.
created_on	String	Date and time the record was created (ISO 8601 format).
last_updated_by	String	Name of the user who last updated the record.
last_updated_on	String	Date and time the record was last updated (ISO 8601 format).
custom_attributes	Array	Additional attributes defined for the usage record.
custom_attributes.name	String	Name of the custom attribute.
custom_attributes.value	String	Value of the custom attribute.
pagination.records	Integer	Total number of records.
pagination.limit	Integer	Number of records returned per request.
pagination.offset	Integer	Number of records skipped before results start.
pagination.previous_page	String	URL for the previous page of results.
pagination.next_page	String	URL for the next page of results.

Purpose

This endpoint retrieves detailed information about a specific usage record using its unique UUID.

Use Case

This endpoint is used when a authenticated user need to view the complete details of a specific usage record. It is particularly useful for billing, auditing, or tracking resource consumption linked to a charge item. It returns data such as the charge item details, charging period, quantity, unit of measure, time frame, charge status, and related metadata for accurate tracking and billing.

Path Parameters

Parameter	Type	Description
usage_uuid	String	The unique identifier of the usage record to retrieve.

Query Parameters

This endpoint does not have any query parameters.

Request Body

No request body is required for this endpoint.

Response

The endpoint response provides the details of the usage record, including its UUID, version, associated charge item details, charging period, quantity, unit of measure, type of usage, charge status, creation and update metadata, and any custom attributes.

                JSON
              

                      {
    "usage": {
        "uuid": "UUID",
        "version": "VERSION",
        "charge_item_uuid": "UUID",
        "charge_item_name": "ITEM_NAME",
        "charging_period": "PERIOD_RANGE",
        "quantity": "NUMBER",
        "uom": "UNIT_OF_MEASURE",
        "start_time": "TIMESTAMP",
        "end_time": "TIMESTAMP",
        "type": "USAGE_TYPE",
        "charge_status": "STATUS",
        "source": "EMPTY",
        "created_by": "CREATED_BY",
        "created_on": "TIMESTAMP",
        "last_updated_by": "UPDATED_BY",
        "last_updated_on": "TIMESTAMP",
        "custom_attributes": [
            {
                "name": "ATTRIBUTE_NAME",
                "value": "EMPTY"
            }
        ]
    }
}
                    

Attribute	Type	Description
uuid	String	Unique identifier of the usage record.
version	String	Version of the usage record.
charge_item_uuid	String	UUID of the associated charge item.
charge_item_name	String	Name of the associated charge item.
charging_period	String	Period during which the usage was recorded.
quantity	String	The amount of usage recorded.
uom	String	Unit of measure for the usage (e.g., Minute).
start_time	String	Start time of the usage period.
end_time	String	End time of the usage period.
type	String	Type of usage (e.g., INCREMENTAL).
charge_status	String	Status of the charge (e.g., ACTIVE).
source	String	Source of the usage record.
created_by	String	User who created the record.
created_on	String	Timestamp when the record was created.
last_updated_by	String	User who last updated the record.
last_updated_on	String	Timestamp of the last update.
custom_attributes	Array	List of custom attributes with name and value.

Retrieve Usage Records : /usages

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Retrieve Usage Details by UUID : /usages/{usage_uuid}

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response