OpenAPI Specification
openapi: 3.0.1
info:
contact:
email: support@suger.io
name: Suger Support
url: https://www.suger.io/support
description: CRUD operations on a set of resources, including organizations, products, offers, entitlements, usage record groups for meterting, etc.
title: Suger API Metering API
version: '1.0'
servers:
- url: https://api.suger.cloud
tags:
- description: Access to Usage Metering resources
name: Metering
paths:
/org/{orgId}/batchCreateUsageRecordGroups:
post:
description: Batch report new usage record groups.
operationId: BatchReportUsageRecordGroups
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/NewUsageRecordGroup'
type: array
description: Array of new usage record groups to report
required: true
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/MeteringUsageRecordGroup'
type: array
description: OK
'400':
content:
application/json:
schema:
type: string
description: all the quantity of usage records are zero
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Batch Report UsageRecordGroups
tags:
- Metering
x-codegen-request-body-name: usageRecordGroups
/org/{orgId}/batchValidateUsageRecordGroups:
post:
description: Provide a batch of usage record groups and validate each individual usage record group one by one.
operationId: BatchValidateUsageRecordGroups
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/NewUsageRecordGroup'
type: array
description: Array of usage record groups to be validated
required: true
responses:
'200':
content:
application/json:
schema:
type: string
description: Empty string if validation is successful
'400':
content:
application/json:
schema:
type: string
description: Bad request error description
'500':
content:
application/json:
schema:
type: string
description: validation failed for usage record group
security:
- APIKeyAuth: []
summary: Batch Validate UsageRecordGroups
tags:
- Metering
x-codegen-request-body-name: data
/org/{orgId}/billableMetric:
get:
description: list billable metrics for the given organization.
operationId: ListBillableMetrics
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: Status of the billable metric
explode: true
in: query
name: status
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/BillableMetric'
type: array
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: List Billable Metrics
tags:
- Metering
post:
description: Create a new billable metric for the given organization.
operationId: CreateBillableMetric
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BillableMetric'
description: RequestBody
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BillableMetric'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request params
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Create Billable Metric
tags:
- Metering
x-codegen-request-body-name: data
/org/{orgId}/billableMetric/{billableMetricId}:
get:
description: Get the billable metric for the given organization and billable metric ID.
operationId: GetBillableMetric
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: Billable Metric ID
explode: false
in: path
name: billableMetricId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BillableMetric'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'404':
content:
application/json:
schema:
type: string
description: billable metric not found
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Get Billable Metric
tags:
- Metering
patch:
description: Update the name, description and status of the billable metric for the given organization.
operationId: UpdateBillableMetric
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: Billable Metric ID
explode: false
in: path
name: billableMetricId
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBillableMetricParams'
description: RequestBody
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BillableMetric'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'404':
content:
application/json:
schema:
type: string
description: billable metric not found
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Update Billable Metric
tags:
- Metering
x-codegen-request-body-name: data
/org/{orgId}/entitlement/{entitlementId}/usageRecordGroup:
post:
description: It is recommended to provide the ID in the request body CreateUsageRecordGroupParams, so the report can be deduplicated. All duplicate report will return error code 409.
operationId: ReportUsageRecordGroup
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: Entitlement ID
explode: false
in: path
name: entitlementId
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUsageRecordGroupParams'
description: RequestBody
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MeteringUsageRecordGroup'
description: OK
'400':
content:
application/json:
schema:
type: string
description: all the quantity of usage records are zero
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Report UsageRecordGroup
tags:
- Metering
x-codegen-request-body-name: data
/org/{orgId}/usageMeteringConfigInfo:
get:
description: Get the usage metering config info of the given organization.
operationId: GetUsageMeteringConfigInfo
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UsageMeteringConfigInfo'
description: Usage metering config info
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Get Usage Metering Config Info
tags:
- Metering
patch:
description: Update the usage metering config info of the given organization.
operationId: UpdateUsageMeteringConfigInfo
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UsageMeteringConfigInfo'
description: The usage metering config info to be updated
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UsageMeteringConfigInfo'
description: Usage metering config info
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Update Usage Metering Config Info
tags:
- Metering
x-codegen-request-body-name: data
/org/{orgId}/usageRecordGroup:
get:
description: 'List UsageRecordGroups by the given organization, partner, product, entitlement or buyer. Only provide one or none of the optional query parameters: partner, productId, entitlementId & buyerId .'
operationId: ListUsageRecordGroups
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: Cloud Partner
explode: true
in: query
name: partner
required: false
schema:
enum:
- AWS
- AZURE
- GCP
type: string
style: form
- description: filter by buyer ID, default no filter by buyerId if not provided
explode: true
in: query
name: buyerId
required: false
schema:
type: string
style: form
- description: filter by entitlement ID, default no filter by entitlementId if not provided
explode: true
in: query
name: entitlementId
required: false
schema:
type: string
style: form
- description: The status of the usage record group, default no filter by status if not provided
explode: true
in: query
name: status
required: false
schema:
enum:
- CREATED
- DELETED
- INVALID
- REPORTED
- REPORT_PENDING
- REPORT_FAILED
type: string
style: form
- description: The source of the usage record group, default no filter by source if not provided
explode: true
in: query
name: source
required: false
schema:
enum:
- ''
- API
- INTERNAL
- LAGO
- METRONOME
- ORB
- STRIPE
type: string
style: form
- description: metaInfo filter
explode: true
in: query
name: metaInfo
required: false
schema:
type: string
style: form
- description: start date (UTC) in YYYY-MM-DD format, default is 30 days before the endDate
explode: true
in: query
name: startDate
required: false
schema:
type: string
style: form
- description: end date (UTC) in YYYY-MM-DD format, default is today
explode: true
in: query
name: endDate
required: false
schema:
type: string
style: form
- description: List pagination size, default 1000, max value is 1000
explode: true
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: List pagination offset, default 0
explode: true
in: query
name: offset
required: false
schema:
type: integer
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListUsageRecordGroupsResponse'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: List UsageRecordGroups
tags:
- Metering
/org/{orgId}/usageRecordGroup/{usageRecordGroupId}:
delete:
description: delete the UsageRecordGroup for the given organization and usageRecordGroup ID. Only usageRecordGroup with status "CREATED" or "INVALID" can be deleted.
operationId: DeleteUsageRecordGroup
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: UsageRecordGroup ID
explode: false
in: path
name: usageRecordGroupId
required: true
schema:
type: string
style: simple
- description: UsageRecordGroup's creation date (UTC) in YYYY-MM-DD format
explode: true
in: query
name: creationDate
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MeteringUsageRecordGroup'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'404':
content:
application/json:
schema:
type: string
description: usageRecordGroup not found
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Delete UsageRecordGroup
tags:
- Metering
/org/{orgId}/usageRecordGroup/{usageRecordGroupId}/retry:
post:
description: Retry the given UsageRecordGroup by setting from status "REPORT_FAILED" to "CREATED", and it will be ready for the next hourly report. Only usageRecordGroup with status "REPORT_FAILED" can be retried.
operationId: RetryUsageRecordGroup
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: UsageRecordGroup ID
explode: false
in: path
name: usageRecordGroupId
required: true
schema:
type: string
style: simple
- description: UsageRecordGroup's creation date (UTC) in YYYY-MM-DD format
explode: true
in: query
name: creationDate
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MeteringUsageRecordGroup'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'404':
content:
application/json:
schema:
type: string
description: usageRecordGroup not found
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: Retry UsageRecordGroup
tags:
- Metering
/org/{orgId}/usageRecordReport:
get:
description: List usageRecordReports under the given organization, partner, entitlement or buyer, within the given time range and pagination.
operationId: ListUsageRecordReports
parameters:
- description: Organization ID
explode: false
in: path
name: orgId
required: true
schema:
type: string
style: simple
- description: Cloud Partner
explode: true
in: query
name: partner
required: false
schema:
enum:
- AWS
- AZURE
- GCP
type: string
style: form
- description: buyer ID
explode: true
in: query
name: buyerId
required: false
schema:
type: string
style: form
- description: entitlement ID
explode: true
in: query
name: entitlementId
required: false
schema:
type: string
style: form
- description: start date (UTC) in YYYY-MM-DD format, default is 30 days before the endDate
explode: true
in: query
name: startDate
required: false
schema:
type: string
style: form
- description: end date (UTC) in YYYY-MM-DD format, default is today
explode: true
in: query
name: endDate
required: false
schema:
type: string
style: form
- description: List pagination size, default 1000, max value is 1000
explode: true
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: List pagination offset, default 0
explode: true
in: query
name: offset
required: false
schema:
type: integer
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListUsageRecordReportsResponse'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad request error
'500':
content:
application/json:
schema:
type: string
description: Internal server error
security:
- APIKeyAuth: []
summary: List UsageRecordReports
tags:
- Metering
components:
schemas:
MeteringUsageRecordReportInfo:
example:
creditRecords:
key: 2.3021358869347655
usedCommitAmountIncrement: 1.4894159098541704
gcpMeteringRequest: '{}'
alibabaMeteringResponse: '{}'
usedCommitAmount: 1.0246457001441578
reportedRecords:
key: 1.2315135367772556
usedCreditAmount: 6.84685269835264
alibabaMeteringRequest: '{}'
dimensionUnitListPrice:
key: 9.301444243932576
azureMeteringRequest: '{}'
aggregatedBillableRecords:
- amount: 6.027456183070403
quantity: 1.4658129805029452
name: name
billableMetricInfo:
groupBys:
- groupBys
- groupBys
propertyUniqueOn: propertyUniqueOn
filterGroups:
- filters:
- valueType: STRING
name: name
operation: IS
value: '{}'
- valueType: STRING
name: name
operation: IS
value: '{}'
- filters:
- valueType: STRING
name: name
operation: IS
value: '{}'
- valueType: STRING
name: name
operation: IS
value: '{}'
groupBysExpression: groupBysExpression
billableMetricAggregationType: COUNT
key: key
uniqueCountAggregationResult: '{}'
- amount: 6.027456183070403
quantity: 1.4658129805029452
name: name
billableMetricInfo:
groupBys:
- groupBys
- groupBys
propertyUniqueOn: propertyUniqueOn
filterGroups:
- filters:
- valueType: STRING
name: name
operation: IS
value: '{}'
- valueType: STRING
name: name
operation: IS
value: '{}'
- filters:
- valueType: STRING
name: name
operation: IS
value: '{}'
- valueType: STRING
name: name
operation: IS
value: '{}'
groupBysExpression: groupBysExpression
billableMetricAggregationType: COUNT
key: key
uniqueCountAggregationResult: '{}'
awsMeteringResponse: '{}'
dimensionUnitPrice:
key: 3.616076749251911
startTime: 2000-01-23 04:56:07+00:00
decimalParts:
key: 7.061401241503109
newDecimalParts:
key: 4.145608029883936
recordsToReportBeforeAdjustmentAtListPrice:
key: 7.386281948385884
azureMeteringResponse: '{}'
message: message
dimensionCategories:
key: dimensionCategories
awsMeteringRequest: '{}'
usedCreditAmountIncrement: 7.457744773683766
gcpMeteringResponse: '{}'
partner: partner
includedRecords:
key: 2.027123023002322
endTime: 2000-01-23 04:56:07+00:00
creditAmount: 5.637376656633329
commitAmount: 5.962133916683182
usageRecordGroupIds:
- usageRecordGroupIds
- usageRecordGroupIds
status: ''
properties:
aggregatedBillableRecords:
description: The aggregated billable records from the usage metering API v2.
items:
$ref: '#/components/schemas/AggregatedMeteringUsageRecord'
type: array
alibabaMeteringRequest:
allOf:
- $ref: '#/components/schemas/client.PushMeteringDataRequest'
description: The raw request to call Alibaba metering service.
type: object
alibabaMeteringResponse:
allOf:
- $ref: '#/components/schemas/client.PushMeteringDataResponseBody'
description: The raw response from Alibaba metering service.
type: object
awsMeteringRequest:
allOf:
- $ref: '#/components/schemas/AwsMarketplaceMeteringBatchMeterUsageInput'
description: The raw request to call AWS metering service.
type: object
awsMeteringResponse:
allOf:
- $ref: '#/components/schemas/marketplacemetering.BatchMeterUsageOutput'
description: The raw response from AWS metering service.
type: object
azureMeteringRequest:
allOf:
- $ref: '#/components/schemas/AzureMarketplaceMeteringBatchUsageEvent'
description: The raw request to call Azure metering service.
type: object
azureMeteringResponse:
allOf:
- $ref: '#/components/schemas/github_com_sugerio_marketplace-service_third_party_azure_sdk_marketplacemeteringv1.BatchUsageEventOkResponse'
description: The raw response from Azure metering service.
type: object
commitAmount:
description: The amount of the commit if applicable.
type: number
creditAmount:
description: The amount of the credit if applicable.
type: number
creditRecords:
additionalProperties:
type: number
description: The credit usage records in the map of <DimensionKey, Count> for usage metering API v1.
type: object
decimalParts:
additionalProperties:
type: number
description: 'The decimal parts of the usage dimension quantity in the map of <DimensionKey, DecimalPart>,
before this usage record report.'
type: object
dimensionCategories:
additionalProperties:
type: string
description: 'The categories of the usage records in the map of <DimensionKey, Category>.
The dimension category is required when reporting usage records to Alibaba Marketplace.
It comes from the metering dimension category.'
type: object
dimensionUnitListPrice:
additionalProperties:
type: number
description: The public list price of each dimension in the map of <DimensionKey, UnitPrice>.
type: object
dimensionUnitPrice:
additionalProperties:
type: number
description: 'The unit price of each dimension in the map of <DimensionKey, UnitPrice>.
It can be the negotiated price in the private offer or the public list price.'
type: object
endTime:
description: time in UTC when the UsageRecordReport ends
format: date-time
type: string
gcpMeteringRequest:
allOf:
- $ref: '#/components/schemas/GcpMarketplaceMeteringOperation'
description: The raw request to call GCP metering service.
type: object
gcpMeteringResponse:
allOf:
- $ref: '#/components/schemas/servicecontrol.ReportResponse'
description: The raw response from GCP metering service.
type: object
includedRecords:
additionalProperties:
type: number
description: The included usage records in the map of <DimensionKey, Count> for usage metering API v1.
type: object
message:
type: string
newDecimalParts:
additionalProperties:
type: number
description: 'The decimal parts of the usage dimension quantity in the map of <DimensionKey, DecimalPart>,
after this usage record report.'
type: object
partner:
description: The partner where this usage record report is sent to. Such as AWS, AZURE or GCP.
type: string
recordsToReportBeforeAdjustmentAtListPrice:
additionalProperties:
type: number
description: 'The usage records to report before the adjustment by the commit with additional usage at list price,
in the map of <DimensionKey, Count>.'
type: object
reportedRecords:
additionalProperties:
type: number
description: The reported usage records in the map of <DimensionKey, Count> for usage metering API v1.
type: object
startTime:
description: time in UTC when the UsageRecordReport starts
format: date-time
type: string
status:
$ref: '#/components/schemas/UsageRecordReportStatus'
usageRecordGroupIds:
description: The IDs of UsageRecordGroups aggregated in this UsageRecordReport.
items:
type: string
type: array
usedCommitAmount:
description: The amount of the used commit before this usage record report if applicable.
type: number
usedCommitAmountIncrement:
description: The amount of the used commit increment in this usage record report if applicable.
type: number
usedCreditAmount:
description: The amount of the used credit before this usage record report if applicable.
type: number
usedCreditAmountIncrement:
description: The amount of the used credit increment in this usage record report if applicable.
type: number
type: object
github_com_sugerio_marketplace-service_third_party_azure_sdk_marketplacemeteringv1.UsageEventConflictResponse:
properties:
additionalInfo:
$ref: '#/components/schemas/github_com_sugerio_marketplace-service_third_party_azure_sdk_marketplacemeteringv1.UsageEventConflictResponseAdditionalInfo'
code:
type: string
message:
type: string
type: object
AwsMarketplaceMeteringUsageAllocation:
properties:
AllocatedUsageQuantity:
description: The total quantity allocated to this bucket of usage.
type: integer
Tags:
description: 'The set of tags that define the bucket of usage. For the bucket of items with no
tags, this parameter can be left out.'
items:
$ref: '#/components/schemas/AwsMarketplaceMeteringTag'
type: array
type: object
NewUsageRecordGroup:
example:
metaInfo: '{}'
records:
key: 0.8008281904610115
billableRecords:
- quantity: 0.8008281904610115
key: key
properties:
key: ''
- quantity: 0.8008281904610115
key: key
properties:
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suger/refs/heads/main/openapi/suger-metering-api-openapi.yml