Listing Usages

Function: usage_list()

Purpose

This API retrieves the full paginated list of usage records logged against billable charge items via GET /api/v3/usages. The response returns a usages array — each entry exposing identification (uuid, version), the bound charge item (chargeItemUuid, chargeItemName, uom), the metering window (chargingPeriod, startTime, endTime), the recorded quantity, the increment type (e.g. INCREMENTAL), the charge status, the source/origin marker, audit metadata (createdBy, createdOn, lastUpdatedBy, lastUpdatedOn), tenant-defined custom attributes, and an optional usage reference — alongside a standard pagination block (records, limit, offset, previous/next page URLs). Snake_case API keys are mapped to camelCase DTO fields automatically by the SDK's deserializer.

Parameters

Use Case

Billing and metering teams need a full sweep of every recorded usage event — across orders, accounts, and charge items — to drive invoicing runs, audit reconciliation, and downstream analytics. Building this view by walking each order is brittle; the dedicated usage-listing endpoint avoids that fan-out by returning every usage record in a single paginated payload. Telco and SaaS integrations consume the listing to verify that batch usage uploads landed correctly. Finance pipelines pull the list to compute revenue accruals against unbilled usage. The Python SDK exposes this through order.usage_list() returning a strongly typed UsageListDTO.

Response

On success, the function returns a UsageListDTO containing a usages list of UsageDataDTO entries (one per usage record) and a pagination block (PaginationDTO). Each usage entry exposes 18 fields — uuid, version, chargeItemUuid, chargeItemName, chargingPeriod, quantity, uom, startTime, endTime, type, chargeStatus, source, createdBy, createdOn, lastUpdatedBy, lastUpdatedOn, customAttributes, and usageReference — covering identification, charge binding, metering window, audit, and runtime state.

Retrieving Usage Details

Function: usage_details()

Purpose

This API retrieves a single usage record by its UUID via GET /api/v3/usages/{uuid}. The response returns the full usage object — chargeItemUuid binding, metering window (startTime, endTime, chargingPeriod), quantity, increment type, charge status, source/origin marker, audit fields, custom attributes, and an optional usage reference. The SDK exposes this through order.usage_details(uuid) returning a typed UsageDataDTO. The endpoint underpins record-level inspection workflows (drill-down from a usage list, dispute resolution, mid-billing-cycle audit).

Parameters

Use Case

Billing analysts and customer success agents drill into individual usage records when an end customer disputes a charge, when a metering integration reports a mismatch, or when the team needs to confirm that a specific event was captured before invoicing closes. Reconciliation tooling fetches one record at a time to compare against the source-of-truth metering store. Support workflows invoke this endpoint from a usage detail page to render the full state of a single record before allowing further modify/update/delete actions.

Response

On success, the function returns a UsageDataDTO carrying the full usage record. Note: the SDK currently binds the response object directly to UsageDataDTO (flat, no envelope). All 18 fields are populated where the API returned a value.

Adding a Single Usage

Function: add_usage()

Purpose

This API submits a single usage record against a billable charge item via POST /api/v3/usages. The request wraps the new usage under a usage root key and supplies the chargeItemUuid binding, metering window (chargingPeriod, startTime, endTime), recorded quantity, and increment type (e.g. INCREMENTAL). The system persists the record, computes its charge status against the bound rating rule, and returns the created object — including system-generated fields (uuid, version, chargeStatus, source, audit timestamps). The SDK exposes this through order.add_usage(request_data) accepting a UsageCreateDTO and returning the post-create state for immediate caching/UI refresh.

Parameters

Use Case

Telco metering pipelines, SaaS API gateways, and IoT platforms call this endpoint event-by-event when streaming low-volume usage in real time. CRM and customer-portal integrations call it to log discretionary usage adjustments (manual concessions, courtesy credits, one-off events) outside of bulk batches. The single-usage path is also used for retry-of-one in batch flows where a specific record failed validation and needs an isolated retry. The Python SDK now covers this in parity with the .NET SDK via order.add_usage().

Response

On success, the function returns a UsageCreateDTO wrapping the created UsageDataDTO under the usage field. The returned object reflects the persisted state including the new uuid, version, computed chargeStatus, source, and audit fields.

Adding Multiple Usages (Bulk)

Function: add_multiple_usage()

Purpose

This API submits multiple usage records in a single call against the same POST /api/v3/usages endpoint, discriminated by payload shape. The bulk request wraps records under a usages array (alongside an optional pagination block) and the response splits results into a success array (records that persisted cleanly) and a failed array (records that hit validation or rating errors). The system processes each record independently — partial failures do not roll back successful inserts — so callers receive both halves of the outcome and can retry only the failed items. The SDK exposes this through order.add_multiple_usage(request_data) accepting a MultipleUsageCreateDTO and returning a MultipleUsageResponseDTO.

Parameters

Use Case

High-volume metering integrations (telco call records, SaaS API hit counters, IoT device events) batch usage submissions to reduce request overhead and stay within rate limits. Daily/hourly ETL jobs build the full batch from a staging store and submit in one call, then fan-out retries only against the failed half of the response. Migration scripts loading historical usage during a tenant cutover use the bulk path to seed thousands of pre-aggregated records without flooding the single-record endpoint. The Python SDK exposes order.add_multiple_usage() returning a typed split response so callers do not need to parse raw JSON.

Response

On success, the function returns a MultipleUsageResponseDTO carrying a success list of UsageDataDTO entries (records that persisted cleanly with their generated uuid/version/audit fields) and a failed list of UsageDataDTO entries (records the API rejected). Callers can iterate the failed list to build a retry batch without re-submitting the entire payload.

Modifying a Usage (PATCH)

Function: usage_modify()

Purpose

This API applies a partial update to an existing usage record by its UUID via PATCH /api/v3/usages/{uuid}. Only the fields supplied in the payload are touched — every other field on the record is left untouched. The system applies the change, increments the record version, and returns the updated state wrapped in a usage root key. The SDK exposes this through order.usage_modify(uuid, request_data) accepting a UsageCreateDTO and returning a UsageModifyDataDTO. Use this when only the quantity, metering window, or a custom attribute needs to change.

Parameters

Use Case

Customer success agents and billing analysts use this endpoint when a recorded usage event needs a small correction — fixing a typo in the quantity, adjusting the metering window after a meter-reading reconciliation, or attaching a freshly added custom attribute — without re-submitting the entire record. Mid-cycle dispute resolution flows rely on PATCH because POST would create a duplicate and PUT would force the caller to re-send all the unchanged fields. Audit pipelines also use PATCH to backfill missing custom attributes onto historical records as part of metadata cleanup runs.

Response

On success, the function returns a UsageModifyDataDTO wrapping the updated UsageDataDTO under the usage field. The returned object reflects the post-update state with the bumped version and refreshed audit fields.

Updating a Usage (PUT)

Function: usage_update()

Purpose

This API replaces an existing usage record by its UUID via PUT /api/v2/usages/{uuid} (note: the SDK currently routes PUT to v2; PATCH and the rest of the family are on v3). PUT is the full-replace counterpart to PATCH — every supplied field overwrites the stored value, and any field omitted from the payload may be cleared depending on tenant configuration. The SDK exposes this through order.usage_update(uuid, request_data) accepting a UsageCreateDTO and returning a UsageUpdateDataDTO.

Parameters

Use Case

Migration scripts replacing legacy usage records with cleaned/canonicalized versions during a data quality remediation pass use PUT to guarantee the post-state matches the supplied payload exactly — no partial-merge surprises. Integration systems that own the source-of-truth metering store and want to keep Exsited usage in lock-step with their version often prefer PUT over PATCH for deterministic overwrite semantics. Note that because the SDK still routes this PUT to the v2 endpoint, callers should validate field-level coverage against the v2 contract until the SDK URL is bumped to v3.

Response

On success, the function returns a UsageUpdateDataDTO wrapping the replaced UsageDataDTO under the usage field. The returned object reflects the post-replace state with the bumped version and refreshed audit fields.

Deleting a Usage

Function: usage_delete()

Purpose

This API deletes a usage record by its UUID via DELETE /api/v3/usages/{uuid}. Removal drops the record from rating/invoicing pipelines going forward; existing invoices already generated from the record are preserved as audit trail (the deletion does not retroactively credit a finalised invoice). On success the API responds with HTTP 204 No Content. This is a destructive operation — callers should confirm intent before invoking, especially against records already mid-cycle.

Parameters

Use Case

Billing analysts removing usage records that were submitted in error (duplicate batch upload, wrong account binding, test data accidentally promoted to production) use this endpoint to clean up before invoicing close. Migration scripts purging legacy or invalid records during a tenant cleanup run rely on the same endpoint. Because deletion ripples through rating and invoice computation, it is gated behind explicit user confirmation in tooling — the SDK exposes order.usage_delete(uuid) for the underlying call.

Response

On success, the API responds with HTTP 204 No Content. The SDK does not bind a response DTO for this operation — callers should check that no exception was raised. No response body is delivered.