Usages PATCH API Documentation

Purpose

This API is used to partially update an existing usage record. It allows modifying specific attributes such as quantity, end time, custom attributes, or usage notes without overwriting the entire usage record.

Use Case

When a usage entry has been recorded but certain fields need correction or modification. For example, adjusting the quantity used or updating the end time, this API provides a way to make those selective changes without affecting other existing data.

Path Parameters

Parameter	Type	Description
usage_uuid	UUID	Unique identifier of the usage record to be updated.

Query Parameters

This endpoint does not have any query parameters.

Request Body

                JSON
              

                      {
    "usage": {
        "quantity": "{{quantity}}",
        "end_time": "{{end_time}}"
        // "custom_attributes": [
        //     {
        //         "name": "{{attribute_name}}",
        //         "value": "{{attribute_value}}"
        //     }
        // ],
        // "usage_note": "{{usage_note}}"
    }
}

                    

Attribute	Type	Description
usage	Object	Container for usage data.
quantity	String	The quantity value to update.
end_time	DateTime	The updated end time of the usage record in YYYY-MM-DD HH:MM:SS format.
custom_attributes	Array	Optional list of user-defined custom attributes.
name	String	Name of the custom attribute.
value	String	Value of the custom attribute.
usage_note	String	Optional note or description about the usage record.

Response

The response returns the updated usage record, reflecting the modified fields such as quantity and end time. It also includes details such as version, charging period, charge item references, creation and last update metadata, and any defined custom attributes. This response confirms that the partial update was successful and provides the complete updated state of the usage record.

Response Body

                JSON
              

                      {
    "usage": {
        "uuid": "{{usage_uuid}}",
        "version": "{{version}}",
        "charge_item_uuid": "{{charge_item_uuid}}",
        "charge_item_name": "{{charge_item_name}}",
        "charging_period": "{{charging_period}}",
        "quantity": "{{quantity}}",
        "uom": "{{uom}}",
        "start_time": "{{start_time}}",
        "end_time": "{{end_time}}",
        "type": "{{type}}",
        "charge_status": "{{charge_status}}",
        "source": "{{source}}",
        "created_by": "{{created_by}}",
        "created_on": "{{created_on}}",
        "last_updated_by": "{{last_updated_by}}",
        "last_updated_on": "{{last_updated_on}}",
        "custom_attributes": []
    }
}

                    

Attribute	Type	Description
usage	Object	Contains the updated usage record details.
uuid	UUID	Unique identifier of the usage record.
version	String	Version number of the usage record after update.
charge_item_uuid	UUID	Identifier of the associated charge item.
charge_item_name	String	Name of the charge item related to the usage.
charging_period	String	The period during which the usage applies.
quantity	String	Updated usage quantity.
uom	String	Unit of measurement for the usage.
start_time	DateTime	Start time of the usage period.
end_time	DateTime	Updated end time of the usage period.
type	String	Type of usage (example: INCREMENTAL).
charge_status	String	Current status of the charge (example: ACTIVE).
source	String	Indicates the origin of the record if available.
created_by	String	User who originally created the record.
created_on	DateTime	Timestamp of when the record was created.
last_updated_by	String	User who last modified the record.
last_updated_on	DateTime	Timestamp of the last modification.
custom_attributes	Array	List of any custom attributes applied to this usage.