Reporting Metered Usage to Oracle Marketplace

Marketplace supports usage-based commercial models for both public and private Marketplace offers. For these offers, partners are responsible for reporting customer consumption to Marketplace so that usage can be processed for billing, reconciliation, and reporting.

Partners can submit usage records either individually for near real-time reporting or in batches for high-volume workloads. Each submitted usage record represents billable customer consumption for a Marketplace offer and must contain the information required by Marketplace to uniquely identify, validate, and process the record.

Each usage record must identify:

A unique usage record identifier that supports idempotency, traceability, and duplicate detection.
The Marketplace offer associated with the customer entitlement.
The billable amount, as applicable.
The reporting currency.
The start and end timestamps of the usage interval in UTC.
The usage dimension associated with the billing record, or the literal value "usage" when no usage dimension is available.

Supported Submission Methods


Method	Request format	Recommended use
Usage-record submission	application/json	Used to submit metered usage directly to OCI Marketplace via Request Body.
Batch usage submission	application/octet-stream	Used to submit metered usage to OCI Marketplace in a CSV file.

Required IAM Group and Policy

Before submitting usage records, the partner must create a dedicated OCI IAM group or use an existing IAM group that's approved for the integration.

Create or Select an IAM Group

Create a group such as PartnerGroup, or use an existing group that contains the users or principals responsible for submitting Marketplace usage records.

Grant the Required Permission

Add the following IAM policy in the partner tenancy:

Allow group PartnerGroup to {MARKETPLACE_SELF_SUBSCRIPTION_USAGE_RECORD_CREATE} in compartment partner-compartment

Replace:

<PartnerGroup> with the name of the IAM group used for the integration.
<partner-compartment> with the name of the OCI compartment whose OCID is sent in the compartment-id request header.

The policy grants members of the group permission to submit OCI Marketplace usage records for the specified compartment. OCI rejects requests when the authenticated principal isn't authorised by the applicable IAM policy or when the request targets a compartment outside the policy scope.

For security and operational clarity, OCI recommends using a dedicated IAM group and granting access only to the principals required for this integration.

List of APIs

submitUsageRecord - Synchronously submits usage records for marketplace offers.

batchUsageRecords - Asynchronously submits a UTF-8 CSV usage file for marketplace offers.

Idempotency Rules

The Id field uniquely identifies a usage record.

When retrying the same usage record, Partners must reuse the original Id and should submit the same payload values. Partners must not generate a new Id solely because a previous request timed out or failed with a retryable error.

An existing Id must not be reused for a different usage record, amount, currency, or usage dimension.

Retry Strategy

OCI recommends bounded exponential backoff.

Suggested default values:


Setting	Value
Connection Timeout	10 seconds
JSON Request Timeout	60 seconds
CSV Upload Timeout	120 seconds
Maximum Retries	3

If a timeout occurs after transmission has started, the outcome is unknown because OCI might have already processed the request. Any retry should reuse the original usage record identifiers to preserve idempotency.