Report Usage via API

Overview

You report usage to Suger, against a Suger entitlement; Suger aggregates pending usage and submits it to OCI on an hourly cadence. The endpoints are the same generic Metering API used for every marketplace — this page documents the Oracle-specific field semantics.

The two rules that make Oracle different from AWS/Azure/GCP:

1. The value you report is a monetary amount, not a quantity. OCI has no dimension catalog and no per-dimension rate card, so Suger applies no rate — "records": {"usage": 10} bills 10 units of the entitlement’s currency.
2. Usage keys are open. Any key name is accepted and auto-registered on the entitlement the first time it is seen — no dimension configuration in advance. An entitlement may accumulate at most 100 distinct keys.

Endpoints

Auth: Authorization: Bearer <access_token> — see OAuth App.

Prefer the single-group endpoint with your own id for anything automated: the id is the idempotency key, so a retried request cannot double-report. The batch endpoint carries no dedup key.

Supporting operations (aggregate, validate, retry, delete) are documented in the generic Metering API reference.

Request fields — CreateUsageRecordGroupParams

records — the field data dictionary

records is a flat map of usage key → amount:

"records": {
  "usage": 12.5,
  "api-calls": 3.99
}

Response fields — MeteringUsageRecordGroup

Status lifecycle

What Suger submits to OCI

Each key/amount pair becomes one record in OCI’s submitUsageRecords call (at most 100 records per call, all-or-nothing):

Example

Report one group, idempotent by id:

curl -L -X POST 'https://api.suger.cloud/org/YOUR_ORG_ID/entitlement/YOUR_ENTITLEMENT_ID/usageRecordGroup' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "id": "2f9c1e58-9a1b-4c7e-b1d2-8f3a5c6d7e90",
    "records": {
      "usage": 12.5,
      "api-calls": 3.99
    },
    "timestamp": "2026-08-05T00:00:00Z"
  }'

Response (trimmed):

{
  "id": "2f9c1e58-9a1b-4c7e-b1d2-8f3a5c6d7e90",
  "organizationID": "YOUR_ORG_ID",
  "partner": "ORACLE",
  "entitlementID": "YOUR_ENTITLEMENT_ID",
  "buyerID": "gHYis9RKU",
  "records": { "usage": 12.5, "api-calls": 3.99 },
  "status": "CREATED",
  "metaInfo": {
    "originRecords": { "usage": 12.5, "api-calls": 3.99 },
    "timestamp": "2026-08-05T00:00:00Z",
    "source": "API"
  }
}

Report a batch — the body is an array; each entry needs entitlementID + records (the response is the array of created groups, one per entry, with generated ids):

curl -L -X POST 'https://api.suger.cloud/org/YOUR_ORG_ID/batchCreateUsageRecordGroups' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '[
    {
      "entitlementID": "YOUR_ENTITLEMENT_ID",
      "records": { "usage": 0.75 },
      "timestamp": "2026-08-05T00:00:00Z"
    },
    {
      "entitlementID": "ANOTHER_ENTITLEMENT_ID",
      "records": { "api-calls": 4.2 }
    }
  ]'

Since batch entries carry no caller-supplied id, a retried batch request re-creates the groups — use the single-group endpoint when you need idempotency.

Errors