Metering

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

Overview

After an entitlement is created, you report metric usage data to Suger in real time. Suger normalizes usage reporting across AWS, Azure, Google Cloud Platform (GCP), and Oracle Cloud Marketplace (OCI), 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, Lago, or Chargebee 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. To give a customer credit against its usage-based charges, see Usage Credit.

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

A request carries its usage in one of two forms, never both:

• records (v1) — a map from a marketplace usage-metering dimension to a quantity. This is the form Usage Metering walks through.
• billableRecords (v2) — one object per Suger billable metric, keyed by the billable metric’s id.

Request body example, in the billableRecords form:

{
  "id": "0f8b5c2e-4d7a-4b1e-9c3a-6e2d1f0a7b95",
  "organizationID": "your-suger-org-id",
  "entitlementID": "your-suger-entitlement-id",
  "billableRecords": [
    {
      "key": "billable-metric-id-of-the-entitlements-billable-dimension",
      "properties": {
        "custom-property-1": "val1",
        "custom-property-2": "val2"
      },
      "quantity": 10
    }
  ]
}

• id is optional — the UUID of this usage record group, up to 36 characters. If you leave it out, Suger generates one and returns it in the response.
• quantity is the numeric value of the billable metric for this record. Add one object to billableRecords per metric you report.

For the console path and which listing types Suger can meter on your behalf, see Usage Metering.

• 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 Suger already received for the same entitlement in the last 15 days, Suger rejects the submission with HTTP 400 Bad Request and the message usage record group already reported in the last 15 days.

Dimension key and name mapping

In the records form, each 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.

Reporting late usage

Suger does not re-date late usage into the hour it occurred: AWS and Azure receive it in the hour Suger reports it, GCP in an interval reaching back at most three hours, and Oracle with its original timestamps — see Reporting late usage.

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.

To find specific records in Received Usages, type into Search by Record ID or Invoice ID. It matches a record’s ID and the invoice ID the record carries: a Metronome, Orb, or Stripe invoice ID, a Lago subscription ID, or the ERP Invoice ID added when the usage was reported. Separate several IDs with commas to find all of them at once. The download icon exports the rows you found as CSV, with each of those IDs in its own column, so you can reconcile them against the invoice in your billing system. Chargebee invoice IDs are not searched or exported.

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 needs a header row. The console reads these columns by their exact, case-sensitive names and ignores any other column:

Rows for the same entitlement and erpInvoiceID become one usage record group, with the quantities for each dimension added together. The group takes the timestamp of its first row, so upload one period per file. When a buyer holds more than one active entitlement, identify the entitlement (sugerEntitlementId or sugerExternalEntitlementId): a buyer identifier resolves to only one of them.

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: it reports a row whose dimension the entitlement does not have against the entitlement’s first dimension instead of flagging it (Oracle listings are left as they are).
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 are set aside and listed under Invalid Usage Records with the reason, so you can fix them; only the valid rows are reported. If the file has no dimension or quantity column, or none of the identifier columns, every row is rejected with “Invalid usage record; missing dimension, quantity, customerId, sugerBuyerId, sugerExternalBuyerId, sugerEntitlementId or sugerExternalEntitlementId”. Otherwise a flagged row carries its own reason, such as “buyer is not found” or “usage dimension is not found”. A blank quantity is read as 0, not flagged.

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.
• Chargebee — report the metered overage Chargebee has already priced, as an amount, every hour.
• Suger APIs — for custom setups, stream consumption straight from your own backend.

Each connector has its own setup guide: see Billing Integrations.

To connect a platform:

1. Go to Settings > Integrations to view the available connectors.
2. Find your billing platform (Metronome, Orb, Lago, or Chargebee) 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, Suger retrieves usage from your billing platform on that connector’s schedule — hourly or daily, depending on the platform (see Billing Integrations) — and reports it to the marketplace.

Chargebee reports money rather than units, so it takes a few more steps:

• Its connect dialog asks only for your Chargebee site name and API key. Nothing is reported until you open the card’s Edit dialog and turn on Enable Auto Report Usage, which sets Billing Mode to amount.
• Every amount arrives on the single key chargebee, in the entitlement’s currency, and that key has to land on a dimension the entitlement has. Either your product has a dimension keyed or named chargebee, or you map it in Settings > Usage Metering: edit the row of each marketplace you sell through, turn on Enable Dimension Mapping, and map the source dimension key chargebee to the dimension you bill overage through (see Metering dimension conversion). A record whose key matches no dimension is rejected.
• Enter each buyer’s Chargebee customer ID on the buyer. Suger syncs only the buyers that carry one.

Suger then reads each linked buyer’s priced overage every hour, at 5 minutes past the hour, and the records it creates appear under Received Usages with the source CHARGEBEE. For how each Chargebee billing window is settled against its invoice, see Chargebee.

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 a second request with the same id within 15 days with 400 Bad Request, so the customer isn’t double-billed.

How does Suger handle delayed reporting? Suger accepts it, however old its timestamp is, and sends it in the next hourly report: AWS and Azure receive it in the hour Suger reports it, GCP in an interval reaching back at most three hours, and Oracle with its original timestamps.

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.