Metering

Track, report, and aggregate customer usage so Suger can bill it accurately across AWS, Azure, and GCP.

Overview

After an entitlement is created, you report metric usage data to Suger in real time. Suger normalizes usage reporting across AWS, Azure, and Google Cloud Platform (GCP), so your team doesn’t have to maintain a separate billing API for each marketplace. This helps you prevent revenue leakage and stay compliant with contract terms.

Suger aggregates the reported data hourly and daily. When the billing cycle is over, Suger aggregates the total quantity of each billable dimension for the period, calculates the amount of each billable dimension from the aggregated data and the price model of the billable metric, and uses the total to generate the invoice.

You can report usage in several ways:

• Suger Metering API — stream usage from your own backend services.
• Native billing integrations — connect Metronome, Orb, or Lago to route usage automatically.
• Console reporting — report a single event manually or batch-upload a CSV.

The reported usage data can be viewed on the entitlement details page in real time.

Report usage with the Suger Metering API

To report usage for an active buyer contract, your backend services submit a POST request to the Suger Metering API. Suger validates, aggregates, and forwards the records to the respective cloud provider in the format each platform requires.

Use the following APIs to report usage data:

• report usageRecordGroup
• batch report usageRecordGroup

Request body example:

{
  "ID": "request uuid", # Optional, if not provided, suger will generate one and return in the response.
  "organizationID": "your-suger-org-id",
  "entitlementID": "your-suger-entitlement-id",
  "billableRecords": [
    {
 "key": "billable-metric-id-of-the-entitlement's-billable-dimension",
 "properties": {
   "custom-property-1": "val1",
   "custom-property-2": "val2"
 },
 "quantity": 10, # The num of the metric.
    },
    ...
  ]
}

• The organizationID and entitlementID are required. Each request can only report one entitlement’s usage data.
• The billableRecords is an array, you can report multiple metrics in one request.
  • The key is the billable metric id in the entitlement’s billable dimension.
  • The properties is a map of the custom properties of the billable metric, they are used for filter or group by or unique count.
  • The quantity is the number of the metric.

Enforce idempotency with a unique id

To prevent duplicate billing, always provide a unique id in the request body of every metering record.

• Suger uses this identifier to automatically de-duplicate incoming metering events.
• If you submit a payload with an id that has already been processed, Suger rejects the submission and returns an HTTP 409 Conflict.

Dimension key and name mapping

The key you send can be either the marketplace Usage Metering Dimension Key or the Dimension Name. These values are stored under WorkloadEntitlement.info.dimensions for any activated buyer contract, so you can retrieve them there.

Timeframe window limits

Cloud marketplaces enforce rigid windows for submitting historical usage. To keep provider billing engines from rejecting records outright, Suger applies a safety buffer:

• One-hour safety margin — Suger reduces the official marketplace historical reporting limit by exactly one hour.
• Timestamp handling — Records with a timestamp inside the buffered limit are forwarded with their original, unaltered timestamp. Records older than the buffered window are adjusted to the timestamp at the maximum allowable boundary before Suger transmits them.

Report usage from the console

Beyond the API, operations and finance teams can track, log, and audit usage directly on the Usage Metering page. At the top of the dashboard you can toggle between four views:

• Received Usages — raw, individual usage ingest logs as they stream into Suger.
• Hourly / Daily / Monthly Reports — aggregated, time-bucketed consumption summaries for reviewing baseline usage and overage trends.

Report a single usage event

For individual corrections or ad-hoc adjustments, enter a usage event manually:

1. Click + Report Usage on the right side of the panel.
2. Enter the details:
   • Product
   • Entitlement
   • Record Date
   • (Optional) Additional Metadata
   • Usage records
3. Click Report.

You can also report a one-off event directly from an entitlement. Open the Entitlements tab, choose the entitlement, scroll to the Usage Metering section, and specify the record date, usage dimension, and quantity. Make sure the total quantity matches the amount from your internal usage metrics.

Batch-upload a CSV

If you log usage for many customers at once, upload a single structured CSV to report thousands of entries at a time.

Your CSV must include a header row with these exact, case-sensitive columns:

To upload:

1. Open the Usage Metering page from the left-hand console menu.
2. Click Batch Report Usages in the upper right.
3. Choose Upload CSV in the batch window. You can also turn on the Auto Fix toggle.
4. Drag and drop your file into the target, or click to browse.

Once your file lands, Suger validates every row before sending anything to the marketplace:

• Clean rows pass validation and are queued for transmission.
• Flagged rows — if a row has an unrecognized sugerBuyerId, a missing value, or a malformed timestamp, the upload pauses. Invalid rows are highlighted with a specific error (e.g. “Dimension key ‘server_count’ not found”) so you can fix them before only valid entries are reported.

You can also batch report from an entitlement: create a CSV of multiple usage events across multiple dates, upload it in the entitlement’s Usage Metering section, and click Batch Report.

Automate usage with billing integrations

Suger offers native, code-free integrations with leading usage-based billing platforms:

• Metronome — stream transactional usage metrics to marketplace contracts.
• Orb — sync complex, aggregated multi-metric pricing dimensions.
• Lago — map open-source metering to compliant marketplace billing entries.
• Suger APIs — for custom setups, stream consumption straight from your own backend.

To connect a platform:

1. Go to Settings > Integrations to view the available connectors.
2. Find your billing platform (Metronome, Orb, or Lago) and click Connect.
3. Provide the platform’s API credentials and complete the field-mapping step to bind your internal billing dimensions to your marketplace dimension keys.
4. Once active, your billing platform routes usage events to Suger automatically. Suger verifies them and pushes them to the hyperscalers in real time.

Advanced configuration

Metering dimension conversion

If your internal telemetry uses dimension names that differ from the ones configured in the cloud marketplaces, define Metering Dimension Conversion rules to map them automatically. You can also set a multiplier to scale metrics during conversion (for example, converting gigabytes to megabytes).

Commit with additional usage metering (Divide Commit)

For contracts where a buyer prepays a large upfront commitment but you still need to track, segment, or cap usage across milestones, use Commit with additional usage metering to split an entitlement into sub-terms:

1. Open the transaction details and click Divide Commit.
2. Define the start and end dates for each sub-entitlement milestone, then click Divide.
3. The parent term splits into independent tracks so your telemetry can meter usage cleanly within each ring-fenced window.

AWS usage allocation tags

For AWS Marketplace contracts, you can define custom Usage Allocation Tags to break out discrete cost categories in your offers.

• Tags use the usageAllocations map array, binding quantities to UsageAllocationTag key-value pairs.
• Once reported, these allocations propagate to the buyer’s AWS Billing Console, letting enterprise customers view and reconcile usage charges by cost center, tag, or department.

Usage hourly report

Suger aggregates each entitlement’s reported usage data every hour, giving you a real-time view of usage.

• Every hour, Suger aggregates the reported usage data of the previous hour.
• If the billable metric is configured with filters, the usage data is filtered by those filters.
• After hourly aggregation completes, Suger generates the hourly report and marks the original usage data as reported.
• Hourly reports only aggregate the quantity of metrics based on the metric’s aggregation type; they do not calculate the corresponding amount, because the price model needs the total quantity of the whole billing cycle.

Aggregate logic

The aggregation logic is based on the billable metric’s aggregate type, which is set when the billable metric is created.

Aggregation with groupby

If the billable metric is configured with groupby attributes, the usage records are first divided into multiple groups based on the groupby attributes, then aggregated separately according to the aggregation type. The reason is that the billable dimension’s price model is applied to each group.

Aggregation with unique count

If the billable metric is configured with unique count aggregation type, the calculation is more complex.

• First, Suger gets a unique array of the target attribute values from the report records within that hour — in other words, the same value appears only once in the array.
• Then Suger reads all the unique arrays of the previous hourly reports today and removes duplicate values from the current hour’s unique array, making it smaller.
• Finally, the unique array represents the new values’ unique count in this hour of today.

The deduplicate target is only today’s data, so every first hour of each day is a little larger than the other hours.

The hourly reports can be viewed on the entitlement details page.

Usage daily report

Like the hourly report, the daily report of each entitlement is aggregated every day. The daily report is aggregated from the hourly reports instead of the original reported data.

Calculate usage invoice fee

When an entitlement’s billing cycle is over, Suger calculates the usage invoice, which requires aggregating all the report records of the entitlement in the billing cycle. The source of the calculation data is the hourly reports rather than the original reported data, since the hourly reports have already been aggregated.

• First, calculate the aggregated daily quantity of each billable metric within the invoice period based on the hourly report.
• Then calculate the final aggregated quantity of each billable metric based on daily aggregated data.
• Finally, calculate the final fee amount from the quantity according to the price model of each billable metric.

Aggregation with groupby

If the billable metric is configured with groupby attributes, the hourly and daily aggregation results, as well as the total quantity, are calculated for multiple results based on the combination of the groupby attributes.
Each group gets the aggregated quantity, and the price model is applied to each group. The final invoice amount is the sum of all the groups’ amounts.

Aggregation with unique count

If the billable metric is configured with unique count aggregation type, Suger calculates the unique count of the target attribute values from all the report records within the invoice period, still using the hourly reports because each hourly report has already been deduplicated.

• Daily data is aggregated from the hourly reports first. In this step Suger gets a unique array for today by merging all unique arrays of all hourly reports today.
• Then Suger merges and deduplicates all daily unique arrays in the invoice period.
• Finally Suger gets the unique array of the invoice period and its unique count.

Troubleshooting

FAQs

Can I use my internal telemetry names instead of the marketplace dimension keys? Yes. Configure Metering Dimension Conversion rules in Suger, and it maps your internal names to the correct marketplace dimension keys automatically — no need to change your application logic.

What happens if my backend reports the same usage record twice? If you include a unique id (highly recommended), Suger’s de-duplication rejects the second request with a 409 Conflict, so the customer isn’t double-billed.

How does Suger handle delayed reporting? If your telemetry sends a record older than the allowed historical window, Suger pushes it forward to the maximum allowed edge for that marketplace so the event isn’t dropped.

Can my customers see how their usage charges split across business units? Yes, for AWS Marketplace purchases. Implement AWS Usage Allocation Tags to bind metadata to usage records; the tags pass into the customer’s AWS Billing Console, letting them track charges by department or cost center.

Do we need to write code to connect Orb or Metronome? No. These are native, code-free integrations. Authenticate the connection with your billing platform’s API keys and map your usage dimensions.

Can we run an API integration alongside a native billing connector? Yes. Suger supports hybrid workflows — for example, Orb for standard metric counts and direct Suger API calls for ad-hoc professional-service milestones.