Ingest Usage

POST /accounting/usages/ingest

Group: Accounting › Usage · Operation ID: ingestUsage

Ingests one or more usage records through the staging pipeline. Returns a dataExtractionId to poll with GET accounting/usages/ingestions. Processing is asynchronous unless you set sync to true.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: ingestUsageInput.

Field Type Required Description
items array of object yes The usage records to ingest, in the default usage ingestion schema.
items[].usageIdentifier string yes A stable external identifier for this usage record. It is used to identify re-ingested duplicates.
items[].dateTime string yes The date or date and time the usage was recorded against. Use format YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ.
items[].unitOfMeasure string yes The unit the quantity is measured in, for example 'Hour', 'GB' or 'Call'.
items[].quantity string yes The quantity of usage, as a decimal string to keep precision. Send 0 to reset the usage recorded for the period.
items[].usageComponent string no The billable component this usage maps to, by name or identifier. Omit to let Everest resolve it from productIdentifier and unitOfMeasure.
items[].productIdentifier string no The product code or identifier this usage is attributed to. It is used to resolve the billable component when usageComponent is omitted.
items[].trackId string no An identifier you supply to track this row through GET accounting/usages/ingestions.
mapping string no The column mapping to apply. Defaults to 'Usage API Mapping' when omitted.
sync boolean no Whether to wait until ingestion finishes before responding. Defaults to false, which returns at once with a dataExtractionId to poll with GET accounting/usages/ingestions.

Example:

{
  "items": [
    {
      "usageIdentifier": "<usageIdentifier>",
      "dateTime": "<dateTime>",
      "unitOfMeasure": "<unitOfMeasure>",
      "quantity": "<quantity>",
      "usageComponent": "<usageComponent>",
      "productIdentifier": "<productIdentifier>",
      "trackId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "mapping": "<mapping>",
  "sync": true
}

Response

200 Success

Under data (ingestUsageOutput):

Field Type Required Description
data object yes The accepted ingestion job.
data.dataExtractionId number yes The identifier of the ingestion job. Pass it to GET accounting/usages/ingestions to poll per-record results.

Response headers

Errors

Code Status
MAPPING_NOT_FOUND 400
PROCESSING_FAILED 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses