Report usageRecordGroup

POST https://api.suger.cloud/org/{orgId}/entitlement/{entitlementId}/usageRecordGroup

Provide the ID in the request body CreateUsageRecordGroupParams so the report can be deduplicated. Duplicate reports return error code 409.

Parameters

Name	In	Type	Required	Description
`orgId`	path	string	yes	Organization ID
`entitlementId`	path	string	yes	Entitlement ID

Request Body

Required. Content-Type: application/json · Schema: CreateUsageRecordGroupParams

CreateUsageRecordGroupParams fields:

Field	Type	Required	Description
`billableRecords`	array<MeteringUsageRecord>	no	for usage metering API v2, don't use it together with the records v1.
`entitlementID`	string	yes
`id`	string	no	The uuid of the UsageRecordGroup (the size is up to 36 characters). Optional, if not provided, suger will generate one.
`metaInfo`	MeteringUsageRecordGroupMetaInfo	no
`organizationID`	string	yes
`records`	object	yes	for usage metering API v1, don't use it together with the billableRecords v2.
`timestamp`	string	no	The timestamp of when the usage records were generated. Optional, if not provided, the current report timestamp will be used. This is not the timestamp of when the usage records were reported to Suger.
`usageAllocations`	object	no	usage allocation information, dimension key -> usageAllocation array. Only supported for AWS marketplace usage metering at this moment.

MeteringUsageRecord fields:

Field	Type	Required	Description
`key`	string	no	Key is the unique identifier of a billable metric.
`properties`	object	no	Properties is the filters of a billable metric. It should be equal to the filters of the billable metric.
`quantity`	number	no	The quantity (or numeric value) of a billable metric.

MeteringUsageRecordGroupMetaInfo fields:

Field	Type	Required	Description
`SkipValidation`	boolean	no	If it is true, the validation of the usage record group is skipped.
`billableRecords`	array<MeteringUsageRecord>	no	for usage metering API v2
`chargebeeCreditAmount`	number	no	The credit this record granted, as a Chargebee currency amount, added to the entitlement term's credit as-is. Set only on credit markers.
`chargebeeCreditGranted`	boolean	no	Whether the credit in ChargebeeCreditAmount was actually granted on the entitlement term. The marker is written before the grant, so a record carrying an amount with this false is an interrupted grant that the next sync completes rather than leaving the buyer over-billed.
`chargebeeCumulativeAmount`	number	no	The running total accounted for so far for the window, major units. Settlement lowers it to the net invoiced figure, so it is not what the live step diffs against.
`chargebeeGrossAmount`	number	no	The gross Chargebee figure this record was built from, major units. The live counter is gross and never moves when a discount or a void lowers the cumulative, so the live step diffs against this to tell real new usage from an accounting adjustment.
`chargebeeInvoiceID`	string	no	The Chargebee invoice this record settled. Empty on records the hourly step wrote, which read the usage counter before any invoice existed.
`chargebeeMeteredItemPriceID`	string	no	The Chargebee metered addon item price the usage belongs to.
`chargebeeSubscriptionID`	string	no	The Chargebee subscription the usage belongs to. Set on records with source CHARGEBEE.
`chargebeeUsageDateFrom`	integer	no	The start of the Chargebee billing window as unix seconds, matched as an integer.
`erpInvoiceID`	string	no	ERP invoice ID for tracking usage against external ERP service.
`lagoAmount`	number	no	The lago amount (in dollars) of the customer. This field keeps the largest of the monthly amount. So it can only be updated when the invoice month increases.
`lagoSubscriptionID`	string	no	The lago subscription ID of the customer.
`lagoUsageStartTime`	string	no	The lago usage start time of the customer usage.
`metronomeDailyCostAmount`	number	no	The metronome daily cost amount (in dollars) of the customer.
`metronomeInvoiceCreditBack`	boolean	no	Whether the metronome invoice has been credited back.
`metronomeInvoiceCreditBackAmount`	number	no	The metronome invoice amount (in dollars) of the customer.
`metronomeInvoiceID`	string	no	The metronome invoice ID of the customer.
`metronomeMonthlyInvoiceAmount`	number	no	The metronome monthly invoice amount (in dollars) of the customer. This field keeps the largest amount of the invoice month. So it can only be updated when the invoice month increases.
`metronomeMonthlyInvoiceAmountAdjusted`	number	no	The metronome monthly invoice amount (in dollars) of the customer, which is adjusted by the seller. This field is populated only when the invoice amount is decreased by the seller via credit granting.
`orbInvoiceCreditBack`	boolean	no	Whether the void orb invoice has been credited back.
`orbInvoiceCreditBackAmount`	number	no	The credited-back amount (in dollars) for a voided orb invoice.
`orbInvoiceID`	string	no	The orb invoice ID of the customer.
`originRecords`	object	no	The original records reported by the customer before convertion. If no dimension mapping is applied, this field is the same as the records field.
`source`	UsageRecordGroupSource	no
`stripeInvoiceID`	string	no
`stripePeriodEndTime`	string	no	The stripe period end time of the summary or invoice. UTC time in format "YYYY-MM-DDTHH:MM:SSZ".
`stripePeriodStartTime`	string	no	The stripe period start time of the summary or invoice. UTC time in format "YYYY-MM-DDTHH:MM:SSZ".
`stripeSubscriptionItemID`	string	no
`stripeUsageRecordSummaryID`	string	no
`stripeUsageRecordSummaryTotalUsage`	integer	no
`timestamp`	string	no	The timestamp (UTC)) of when the usage records were generated. Optional, if not provided, the current report timestamp will be used.
`usageAllocations`	object	no	usage allocation information, dimension key -> UsageAllocation array. Only supported for AWS marketplace usage metering at this moment.

Responses

200 — OK

Content-Type: application/json · Schema: MeteringUsageRecordGroup

MeteringUsageRecordGroup fields:

Field	Type	Required	Description
`buyerID`	string	no
`creationTime`	string	no
`entitlementID`	string	no
`id`	string	no
`lastUpdateTime`	string	no
`metaInfo`	MeteringUsageRecordGroupMetaInfo	no
`organizationID`	string	no
`partner`	string	no
`records`	object	no
`reportedTime`	string	no	nullable
`serialID`	integer	no
`status`	string	no
`usageRecordReportID`	string	no

MeteringUsageRecordGroupMetaInfo fields:

Field	Type	Required	Description
`SkipValidation`	boolean	no	If it is true, the validation of the usage record group is skipped.
`billableRecords`	array<MeteringUsageRecord>	no	for usage metering API v2
`chargebeeCreditAmount`	number	no	The credit this record granted, as a Chargebee currency amount, added to the entitlement term's credit as-is. Set only on credit markers.
`chargebeeCreditGranted`	boolean	no	Whether the credit in ChargebeeCreditAmount was actually granted on the entitlement term. The marker is written before the grant, so a record carrying an amount with this false is an interrupted grant that the next sync completes rather than leaving the buyer over-billed.
`chargebeeCumulativeAmount`	number	no	The running total accounted for so far for the window, major units. Settlement lowers it to the net invoiced figure, so it is not what the live step diffs against.
`chargebeeGrossAmount`	number	no	The gross Chargebee figure this record was built from, major units. The live counter is gross and never moves when a discount or a void lowers the cumulative, so the live step diffs against this to tell real new usage from an accounting adjustment.
`chargebeeInvoiceID`	string	no	The Chargebee invoice this record settled. Empty on records the hourly step wrote, which read the usage counter before any invoice existed.
`chargebeeMeteredItemPriceID`	string	no	The Chargebee metered addon item price the usage belongs to.
`chargebeeSubscriptionID`	string	no	The Chargebee subscription the usage belongs to. Set on records with source CHARGEBEE.
`chargebeeUsageDateFrom`	integer	no	The start of the Chargebee billing window as unix seconds, matched as an integer.
`erpInvoiceID`	string	no	ERP invoice ID for tracking usage against external ERP service.
`lagoAmount`	number	no	The lago amount (in dollars) of the customer. This field keeps the largest of the monthly amount. So it can only be updated when the invoice month increases.
`lagoSubscriptionID`	string	no	The lago subscription ID of the customer.
`lagoUsageStartTime`	string	no	The lago usage start time of the customer usage.
`metronomeDailyCostAmount`	number	no	The metronome daily cost amount (in dollars) of the customer.
`metronomeInvoiceCreditBack`	boolean	no	Whether the metronome invoice has been credited back.
`metronomeInvoiceCreditBackAmount`	number	no	The metronome invoice amount (in dollars) of the customer.
`metronomeInvoiceID`	string	no	The metronome invoice ID of the customer.
`metronomeMonthlyInvoiceAmount`	number	no	The metronome monthly invoice amount (in dollars) of the customer. This field keeps the largest amount of the invoice month. So it can only be updated when the invoice month increases.
`metronomeMonthlyInvoiceAmountAdjusted`	number	no	The metronome monthly invoice amount (in dollars) of the customer, which is adjusted by the seller. This field is populated only when the invoice amount is decreased by the seller via credit granting.
`orbInvoiceCreditBack`	boolean	no	Whether the void orb invoice has been credited back.
`orbInvoiceCreditBackAmount`	number	no	The credited-back amount (in dollars) for a voided orb invoice.
`orbInvoiceID`	string	no	The orb invoice ID of the customer.
`originRecords`	object	no	The original records reported by the customer before convertion. If no dimension mapping is applied, this field is the same as the records field.
`source`	UsageRecordGroupSource	no
`stripeInvoiceID`	string	no
`stripePeriodEndTime`	string	no	The stripe period end time of the summary or invoice. UTC time in format "YYYY-MM-DDTHH:MM:SSZ".
`stripePeriodStartTime`	string	no	The stripe period start time of the summary or invoice. UTC time in format "YYYY-MM-DDTHH:MM:SSZ".
`stripeSubscriptionItemID`	string	no
`stripeUsageRecordSummaryID`	string	no
`stripeUsageRecordSummaryTotalUsage`	integer	no
`timestamp`	string	no	The timestamp (UTC)) of when the usage records were generated. Optional, if not provided, the current report timestamp will be used.
`usageAllocations`	object	no	usage allocation information, dimension key -> UsageAllocation array. Only supported for AWS marketplace usage metering at this moment.

MeteringUsageRecord fields:

Field	Type	Required	Description
`key`	string	no	Key is the unique identifier of a billable metric.
`properties`	object	no	Properties is the filters of a billable metric. It should be equal to the filters of the billable metric.
`quantity`	number	no	The quantity (or numeric value) of a billable metric.

400 — all the quantity of usage records are zero

Content-Type: application/json

500 — Internal server error

Content-Type: application/json

Example

Generated from this operation's schema. Values are placeholders — substitute your own ids, and set SUGER_TOKEN to a bearer token from the OAuth client-credentials exchange.

Request

curl -X POST 'https://api.suger.cloud/org/{orgId}/entitlement/{entitlementId}/usageRecordGroup' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "entitlementID": "01H0000000000000000000",
  "organizationID": "01H0000000000000000000",
  "records": {}
}'

Response — 200

{
  "buyerID": "01H0000000000000000000",
  "creationTime": "2026-01-31T12:00:00Z",
  "entitlementID": "01H0000000000000000000",
  "id": "01H0000000000000000000",
  "lastUpdateTime": "2026-01-31T12:00:00Z",
  "metaInfo": {
    "SkipValidation": true,
    "billableRecords": [
      {
        "key": "string",
        "properties": {},
        "quantity": 100
      }
    ],
    "chargebeeCreditAmount": 100,
    "chargebeeCreditGranted": true,
    "chargebeeCumulativeAmount": 100,
    "chargebeeGrossAmount": 100,
    "chargebeeInvoiceID": "01H0000000000000000000",
    "chargebeeMeteredItemPriceID": "01H0000000000000000000",
    "chargebeeSubscriptionID": "01H0000000000000000000",
    "chargebeeUsageDateFrom": 1,
    "erpInvoiceID": "01H0000000000000000000",
    "lagoAmount": 100
  },
  "organizationID": "01H0000000000000000000",
  "partner": "AWS",
  "records": {},
  "reportedTime": "2026-01-31T12:00:00Z",
  "serialID": 1,
  "status": "string"
}

Error — 400

"string"

View as Markdown · Interactive API reference

Spotted something wrong or out of date on this page? Tell us and we'll correct it.