Suger Metering API

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