Usages POST API Documentation

Purpose

Create a new usage record against a specific charge item, capturing the metered quantity consumed within a defined charging period and time window. The request wraps a usage object that identifies the target charge item by its UUID, declares the billing window in YYYY-MM-DD-YYYY-MM-DD format, specifies the consumed quantity against the item's unit of measure, and bounds the event with start and end timestamps. The type field controls reconciliation: INCREMENTAL adds the quantity on top of any existing usage already recorded, while absolute/replace modes overwrite the running total. On success the API returns the persisted usage record under a usage wrapper, including the assigned UUID, version, denormalised charge item identity, echoed charging period, normalised quantity and UOM, recorded time window, submission type, resolved charge status, originating source, full audit fields, custom attributes, and an external usage_reference correlation token.

Use Case

Metered and consumption-based products — API call volumes, storage GB-hours, seat counts, transaction counts, energy consumption, telephony minutes, data egress — produce usage events that must be captured against the correct charge item and billing window so the billing engine can rate, aggregate, and invoice them accurately. This endpoint is the entry point that ingests those events. Integration systems push usage from upstream meters (telemetry pipelines, gateway logs, IoT collectors, internal ledgers) into Exsited by calling this endpoint either in near-real-time as events arrive or in periodic batches at the close of a billing window. Operations and finance teams also use it to record manual adjustments — backdated corrections, one-off true-ups, or reconciliations against an external source-of-truth meter — by setting appropriate start time, end time, and charging period so the adjustment lands in the intended billing cycle. The INCREMENTAL type is critical for streaming ingestion patterns where multiple submissions for the same period must accumulate rather than overwrite, while non-incremental types support replace-style sync from authoritative external systems. Because the response returns the resolved charge_status, callers can immediately tell whether the submission has been accepted into a still-open billing window or hit a closed/invoiced period requiring special handling.

Path Parameters

No path parameters required.

Query Parameters

No query parameters required.

Request Body

                JSON
              

                      {
    "usage": {
        "charge_item_uuid": "3cbf2ca7-ce1f-44dc-98ed-9d08716e9250",
        "charging_period": "2024-05-21-2024-06-20",
        "quantity": "82",
        "start_time": "2024-05-21 16:58:57",
        "end_time": "2024-06-04 16:58:57",
        "type": "INCREMENTAL"
    }
}
                    

Response

Returns the persisted usage record wrapped under a usage object. The payload includes the assigned UUID and version, denormalised charge item identity, echoed charging period, normalised quantity and UOM, recorded time window, submission type, resolved charge_status indicating whether the usage has been picked up by invoicing, originating source, full audit fields, custom attributes array, and an external usage_reference correlation token. Errors follow the standard envelope: 404 if the charge item UUID does not exist, 422 for validation failures (malformed charging period, non-numeric quantity, end before start, period mismatch with time window), 401/403 for authorisation failures, and 5xx for server-side issues.

Response Body

                JOSN
              

                      {
    "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": [],
        "usage_reference": "USAGE_REFERENCE"
    }
}
                    

Attribute	Type	Description
usage.uuid	String (UUID)	Unique identifier assigned to the usage record.
usage.version	String	Version number of the usage record.
usage.charge_item_uuid	String (UUID)	UUID of the charge item the usage was recorded against.
usage.charge_item_name	String	Name of the charge item.
usage.charging_period	String	Billing window the usage falls under.
usage.quantity	String	Recorded quantity of usage.
usage.uom	String	Unit of measure for the recorded quantity.
usage.start_time	String (YYYY-MM-DD HH:MM:SS)	Start timestamp of the usage event.
usage.end_time	String (YYYY-MM-DD HH:MM:SS)	End timestamp of the usage event.
usage.type	String	Submission type (e.g., `INCREMENTAL`).
usage.charge_status	String	Resolved charge status of the usage record.
usage.source	String	Origin of the usage record (API, manual, integration).
usage.created_by	String	Username of the creator.
usage.created_on	String (ISO 8601)	Creation timestamp.
usage.last_updated_by	String	Username of the last editor.
usage.last_updated_on	String (ISO 8601)	Last update timestamp.
usage.custom_attributes	Array	Tenant-defined custom attributes for the usage record.
usage.usage_reference	String	External correlation token for the usage record.

Create a Usage Record: /usages