Ingest usage records

Operation ID: ingestUsage

Group: Accounting › Usage

Open in the interactive reference

POST /accounting/usages/ingest

Not retry-safe: A write that does not run in its own transaction, so it cannot offer replay; it refuses Idempotency-Key with 400. Retry only on a natural key the endpoint rejects duplicates on.

Ingests one or more usage records. The column mapping is applied to the records, and then they're imported in the background. To wait until the import finishes before the response, set sync to true.

The response contains a dataExtractionId. To see the outcome of each record, pass it to GET accounting/usages/ingestions.

Parameters

Name In Type Required Description
Api-Version header string · 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.

Request body

Required, application/json: ingestUsageInput.

Field Type Required Description
items array<object> yes The usage records to ingest, in the default usage ingestion schema.
items[].usageIdentifier string yes The subscription the usage belongs to: its external subscription ID or its internal subscription number (SUB-...). A customer name is also accepted when that customer has exactly one subscription. It does not identify the usage record: a record for the same subscription line, usage component, unit of measure and dateTime replaces the current one.
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 have it resolved 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[].description string no A free-form description of the usage record, returned by GET accounting/usages/{id}. Omit to leave it unset. It does not take part in matching, so changing it does not create a new record.
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. 
{
  "items": [
    {
      "usageIdentifier": "<usageIdentifier>",
      "dateTime": "<dateTime>",
      "unitOfMeasure": "<unitOfMeasure>",
      "quantity": "<quantity>",
      "usageComponent": "<usageComponent>",
      "productIdentifier": "<productIdentifier>",
      "description": "<description>",
      "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. 
{
  "data": {
    "data": {
      "dataExtractionId": 0
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
MAPPING_NOT_FOUND 400
PROCESSING_FAILED 400
IDEMPOTENCY_NOT_SUPPORTED 400

Statuses