Suger Metering API

openapi: 3.2.0
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 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:
    PartnerUsageMeteringConfig:
      example:
        enableCommitWithAdditionalUsageAtListPrice: true
        enableDimensionMapping: true
        dimensionMapping:
          key:
            convertionMultiplier: 0.8008281904610115
            dimensionKey: dimensionKey
            mappingMode: '{}'
        partner: '{}'
        enableBillableDimension: true
        enableCommitWithAdditionalUsageMetering: true
        dimensionMappingV2:
          key:
          - convertionMultiplier: 0.8008281904610115
            dimensionKey: dimensionKey
            mappingMode: '{}'
          - convertionMultiplier: 0.8008281904610115
            dimensionKey: dimensionKey
            mappingMode: '{}'
      properties:
        dimensionMapping:
          additionalProperties:
            $ref: '#/components/schemas/UsageMeteringDimensionMappingValue'
          description: 'Deprecated: Use DimensionMappingV2 instead.

            The mapping of the source dimension key to the destination dimension key of the usage metering.'
          type: object
        dimensionMappingV2:
          additionalProperties:
            items:
              $ref: '#/components/schemas/UsageMeteringDimensionMappingValue'
            type: array
          description: 'The mapping of the source dimension key to the destination dimension keys of the usage metering.

            The destination dimension keys are the list of the destination dimension keys.

            So the source dimension key can be mapped to multiple destination dimension keys.'
          type: object
        enableBillableDimension:
          type: boolean
        enableCommitWithAdditionalUsageAtListPrice:
          description: 'Enable the commit (discount) with additional usage metering at list price.

            Only applicable if EnableCommitWithAdditionalUsageMetering is true.

            The default is false, which means the commit with additional usage metering at the discounted price in the private offer.

            If set to true, the additional usage is metered at the list price (the price in public product listing) instead of the discounted price.'
          type: boolean
        enableCommitWithAdditionalUsageMetering:
          description: 'Enable the commit with additional usage metering.

            The default is false, which means all usage records are reported to partner no matter how much is the commit.

            If set to true, the usage records will be reported to partner only if the current commit has been exhausted.'
          type: boolean
        enableDimensionMapping:
          description: 'Enable the dimension mapping for the usage metering.

            The default is false, which means no dimension conversion and just use the origin dimension.'
          type: boolean
        partner:
          allOf:
          - $ref: '#/components/schemas/Partner'
          description: The partner in this dimension mapping. Required. Such as AWS, AZURE or GCP.
          type: object
      type: object
    github_com_sugerio_marketplace-service_third_party_azure_sdk_marketplacemeteringv1.UsageBatchEventOkMessage:
      properties:
        dimension:
          description: Dimension identifier
          type: string
        effectiveStartTime:
          description: Time in UTC when the usage event occurred
          type: string
        error:
          $ref: '#/components/schemas/github_com_sugerio_marketplace-service_third_party_azure_sdk_marketplacemeteringv1.UsageEventConflictResponse'
        messageTime:
          description: Time this message was created in UTC
          type: string
        planId:
          description: Plan associated with the purchased offer
          type: string
        quantity:
          description: Number of units consumed
          type: number
        resourceId:
          description: Identifier of the resource against which usage is emitted
          type: string
        resourceUri:
          description: Identifier of the managed app resource against which usage is emitted
          type: string
        status:
          allOf:
          - $ref: '#/components/schemas/github_com_sugerio_marketplace-service_third_party_azure_sdk_marketplacemeteringv1.UsageEventStatusEnum'
          description: Status of the operation.
          type: object
        usageEventId:
          description: Unique identifier associated with the usage event
          type: string
      type: object
    AzureMarketplaceMeteringUsageEvent:
      properties:
        dimension:
          description: Dimension identifier
          type: string
        effectiveStartTime:
          description: Time in UTC when the usage event occurred
          type: string
        planId:
          description: Plan associated with the purchased offer
          type: string
        quantity:
          description: Number of units consumed
          type: number
        resourceId:
          description: 'subscriptionId property value for SaaS offer subscriptions; resourceUsageId property on the managed application resource

            for managed application offers. For managed applications, only use one of

            resourceId or resourceUri.'
          type: string
        resourceUri:
          description: Resource URI for the managed app. Used with managed applications. Only use resourceUri or resourceId, but never both.
          type: string
      type: object
    AwsMarketplaceMeteringBatchMeterUsageInput:
      properties:
        ProductCode:
          description: 'Product code is used to uniquely identify a product in AWS Marketplace. The

            product code should be the same as the one used during the publishing of a new product.'
          type: string
        UsageRecords:
          description: The set of UsageRecords to submit. BatchMeterUsage accepts up to 25 UsageRecords at a time.
          items:
            $ref: '#/components/schemas/AwsMarketplaceMeteringUsageRecord'
          type: array
      type: object
    types.UsageRecord:
      properties:
        customerIdentifier:
          description: 'The CustomerIdentifier is obtained through the ResolveCustomer operation and

            represents an individual buyer in your application.


            This member is required.'
          type: string
        dimension:
          description: 'During the process of registering a product on AWS Marketplace, dimensions are

            specified. These represent different units of value in your application.


            This member is required.'
          type: string
        quantity:
          description: 'The quantity of usage consumed by the customer for the given dimension and

            time. Defaults to 0 if not specified.'
          type: integer
        timestamp:
          description: 'Timestamp, in UTC, for which the usage is being reported. Your application can

            meter usage for up to one hour in the past. Make sure the timestamp value is

            not before the start of the software usage.


            This member is required.'
          type: string
        usageAllocations:
          description: 'The set of UsageAllocations to submit. The sum of all UsageAllocation

            quantities must equal the Quantity of the UsageRecord .'
          items:
            $ref: '#/components/schemas/types.UsageAllocation'
          type: array
      type: object
    types.UsageRecordResultStatus:
      enum:
      - Success
      - CustomerNotSubscribed
      - DuplicateRecord
      type: string
      x-enum-varnames:
      - UsageRecordResultStatusSuccess
      - UsageRecordResultStatusCustomerNotSubscribed
      - UsageRecordResultStatusDuplicateRecord
    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
    ListUsageRecordReportsResponse:
      example:
        usageRecordReports:
        - organizationID: organizationID
          entitlementTermID: entitlementTermID
          creationTime: 2000-01-23 04:56:07+00:00
          partner: partner
          productID: productID
          entitlementID: entitlementID
          id: id
          buyerID: buyerID
          info:
            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
                

# --- 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