# Usage Metering

:::note
**Usage metering is enabled** (as of August 2026). Suger aggregates each entitlement's pending usage and
submits it to Oracle Cloud Infrastructure hourly. Metered usage bills **in addition to** the offer's
contract value, not instead of it.
:::

## Overview

For usage-based products, Suger reports metered usage back to Oracle Cloud Marketplace (OCI) so buyers are
billed for what they consume. You report usage to Suger with the same
[Metering API](/billing/metering) you use for every other marketplace; Suger submits it to OCI on an
hourly cadence.

Oracle's usage model differs from the other marketplaces in one important way, described next.

## You report an amount, not a quantity

:::warning
For Oracle entitlements, the value you report **is the monetary amount** — not a quantity that Suger
multiplies by a rate. Reporting `10` means **10 units of currency**, not 10 units of consumption.
:::

OCI has no usage-dimension catalog and no per-dimension pricing, so there is no rate for Suger to apply.
This means:

- The value you send is forwarded to OCI as the charge, in the entitlement's currency.
- Your own system owns the pricing calculation — compute the amount before you report it.
- Decimal amounts are supported; the submitted amount is rounded to 5 decimal places (OCI's
  per-record limit), and an amount that rounds to zero is skipped.

If you are porting an integration from AWS, Azure, or GCP, this is the one change you must make: send money
where you previously sent a quantity.

## Usage keys are open

Because there is no dimension catalog to validate against, Oracle accepts **any** usage key:

- You may report against any key name you choose; it is registered on the entitlement the first time it is
  seen, and no configuration step is required in advance.
- The key is submitted to OCI as the `usageDimensionName`.
- An entitlement may accumulate at most **100 distinct usage keys**. This matches the maximum number of
  records OCI accepts in a single submission, so an entitlement that stays within the limit can always be
  reported. Beyond it, further new keys are rejected at ingestion.

## Commit and usage are separate

An offer's commit or prepaid amount does **not** reduce reported usage. Suger forwards Oracle usage exactly
as reported, with no commit, credit, or included-usage deduction applied. Track commit consumption
separately from metered usage.

## Reporting cadence and windows

- Suger aggregates each entitlement's pending usage and submits it to OCI **hourly**.
- A submission carries at most **100 usage records** — one per non-zero usage key — which is OCI's own
  per-call limit.
- A submission is **all-or-nothing**: if OCI rejects any record in the batch, the whole batch is rejected
  and no usage in it is recorded.
- The window Suger tells OCI is the span of the **usage** — from the earliest to the latest usage timestamp
  in the batch — not the hour the run happened to execute in. Usage you report late, or backfill with an
  older timestamp, is therefore attributed to when it actually occurred. The report record you see in
  Suger carries its own, wider window based on when the usage arrived, so the two legitimately differ.
- Zero-amount records are skipped — OCI rejects them, and a report containing only zero amounts is treated
  as a successful no-op.

## Duplicate protection

Each submitted record carries an identifier derived from the usage it represents, so a transient failure
that Suger retries automatically cannot double-bill: OCI recognises the repeat and ignores it. If OCI
reports that the usage was already recorded, Suger treats the submission as successful.

:::warning
Automatic retries are protected, but **manual recovery is not**. If a usage record group is retried by hand
after a failed report, the resubmitted records carry new identifiers, so OCI cannot recognise them as
duplicates. Before retrying a failed Oracle usage record group, confirm in OCI that the usage was not
already recorded.
:::

## Viewing reported usage

Reported Oracle usage appears in the console under **Metering**, with `ORACLE` available in the partner
filter on both the usage list and the aggregated reports. Failed submissions are visible there, and
alerting covers usage that stays unreported.

## Prerequisites

- A verified [Oracle Marketplace integration](/oracle-marketplace/integration).
- An active entitlement derived from an accepted [private offer](/oracle-marketplace/private-offers).
- The OCI IAM policy that permits usage submission must be granted in your partner tenancy. Without it,
  submissions are rejected with an authorization error.