Billing and Usage Reporting¶

Marketplace purchases use the pricing and metering configuration associated with the mapped Omnistrate Plan and the subscription created during fulfillment. Active subscription pricing determines which dimensions are reportable and scales their metered quantities for marketplace billing.

The cloud marketplace, through Suger, remains responsible for invoicing and collecting payment. Omnistrate collects eligible usage, applies the active USD unit price, and sends each dimension key and price-derived quantity to the contract's channel.

Configure Marketplace Billing¶

Before mapping a listing to a Plan:

1. Enable tenant billing for your Omnistrate account.
2. Add MARKETPLACE as a billing provider on the Plan and make it the default when appropriate.
3. Configure the Plan's existing USD price-per-unit values for every dimension that the marketplace should receive.
4. If you use application-specific dimensions, declare them in the Plan's customMetering configuration and configure their prices through the same Plan or subscription pricing model.
5. Configure the corresponding dimensions in Suger. For custom metrics, the Suger dimension key must exactly match the case-sensitive Omnistrate metric name.

See End-to-End Billing for Plan pricing and Send Custom Usage Metrics for custom metric configuration and ingestion.

Choose Where Pricing Is Managed¶

The recommended configuration is to manage the actual unit price in Omnistrate and set the matching dimension rate in Suger and the target marketplace to USD 0.01. A reported quantity of 2,500 is then charged as USD 25.00.

You can instead manage the actual rate in Suger and the target marketplace. Set the Omnistrate unit price to USD 0.01; the calculation then preserves the raw metered quantity. In both configurations, keep the dimension keys identical between Omnistrate and Suger.

Built-In and Custom Usage¶

Omnistrate can report two kinds of usage for a marketplace subscription:

• Built-in dimensions, such as CPU core hours, memory GiB hours, storage GiB hours, replica hours, GPU millicore hours, and deployment cell hours, come from Omnistrate's infrastructure metering.
• Custom dimensions come from events that you send to the custom usage metering endpoint. Omnistrate validates them against the custom metric definitions on the subscription's Plan and applies the configured sum, max, or count aggregation.

The custom metric name is the stable, case-sensitive usage key used in event payloads, pricing, usage views, and marketplace reports. The matching Suger metering dimension must use this exact key. An optional displayName may provide a friendlier label, but it does not replace the metric name as the reporting key.

Omnistrate aggregates accepted custom usage events into hourly quantities using the metric's configured aggregation function. For marketplace-backed subscriptions, eligible hourly usage is reported through Suger or the Sandbox channel.

For each UTC hour, sum adds submitted values, count counts accepted events, and max uses the largest submitted value.

When Reporting Starts and Stops¶

Usage is not reported merely because the marketplace contract is active. The subscription must exist, fulfillment must be ready, and the marketplace contract must permit usage reporting.

For Suger, the marketplace entitlement determines when reporting is permitted. The Sandbox can also simulate a marketplace that delays usage reporting; see Simulation Controls.

How Usage Is Reported¶

After each completed UTC hour, Omnistrate applies active subscription pricing and reports the resulting quantities for eligible marketplace subscriptions. Only dimensions with non-zero active pricing are reported, and reporting begins or stops according to the marketplace lifecycle conditions described above.

Metering shows the underlying usage before price scaling. Usage Reporting shows the price-derived quantity sent to the marketplace. You can inspect each reporting attempt and the channel response. Retries preserve the report identity to prevent duplicate charges; when the channel recognizes a previously accepted report, the attempt is shown as ACCEPTED_BY_DEDUPE.

Verify in the Sandbox¶

The Sandbox runs the production aggregation and reporting path but does not call a billing provider.

1. Connect the Sandbox channel and map a listing to a Plan with marketplace billing and non-zero pricing.
2. Complete a simulated purchase and confirm fulfillment.
3. Create built-in usage by running a deployment, or send custom usage with the subscription ID.
4. Wait for the UTC hour to complete and for the usage to appear.
5. Open FinOps Center → Marketplace Channels, edit the Sandbox channel, and inspect Sandbox usage reports.

Each row shows the record ID, window, dimension, quantity, status, attempt count, contract, and channel result. Sandbox usage is not included in production revenue reporting.

Verify Marketplace Reporting¶

For a fulfilled marketplace subscription:

1. Open FinOps Center → Tenant Metering and select the tenant.
2. In Metering, confirm that the expected dimension and underlying metered quantity appear.
3. Open Usage Reporting and confirm the price-derived outbound quantity from the last seven days.
4. Turn on Failures only when diagnosing a rejected or retrying report.
5. Expand an attempt to compare the usage record, outbound request, channel response, status, and latency.

You can query the same history through the API:

curl --silent --show-error \
  "https://api.omnistrate.cloud/2022-09-01-00/fleet/subscription/${SUBSCRIPTION_ID}/usage-reporting/attempts?failuresOnly=true" \
  --header "Authorization: Bearer ${OMNISTRATE_API_KEY_OR_TOKEN}"

The endpoint defaults to the last seven days and 100 results. You can also filter by record ID, billing channel, status, dimension, or RFC 3339 attempt time, with a maximum limit of 500.

The attempt statuses are:

If a dimension is absent from Usage Reporting, check the subscription's active pricing and exact dimension key.

Configure a billing alarm for MarketplaceUsageReportingFailed to be notified when marketplace usage reporting is rejected by the channel or remains retryable. See Alarms and Webhook Alarm Event Payloads.

Debugging Checklist¶

If usage does not appear in the marketplace:

1. Confirm that the marketplace contract is mapped to the expected production Plan.
2. Confirm that fulfillment is READY and that the contract is not suspended or closed.
3. Confirm that the marketplace contract permits usage reporting.
4. Confirm that the subscription's active pricing contains the exact dimension and expected USD unit price.
5. For custom usage, confirm that the event metric name exactly matches the Plan definition and that the event was accepted by the custom metrics endpoint.
6. In Tenant Metering, verify that the usage exists for the expected UTC hour.
7. In the tenant's Tenant Metering Details, inspect Usage Reporting for PENDING or REJECTED_TERMINAL attempts and review the recorded channel response.
8. In Marketplace Contracts, confirm the subscription ID, channel, lifecycle state, and contract interaction history.