Suger Entitlement 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 Entitlement API
  version: '1.0'
servers:
- url: https://api.suger.cloud
tags:
- description: Access to Entitlement resources
  name: Entitlement
paths:
  /org/{orgId}/entitlement:
    get:
      description: List entitlements under the given organization with pagination and optional filters.
      operationId: ListEntitlements
      parameters:
      - description: Organization ID
        explode: false
        in: path
        name: orgId
        required: true
        schema:
          type: string
        style: simple
      - description: filter by partner
        explode: true
        in: query
        name: partner
        required: false
        schema:
          type: string
        style: form
      - description: filter by productId
        explode: true
        in: query
        name: productId
        required: false
        schema:
          type: string
        style: form
      - description: filter by offerId
        explode: true
        in: query
        name: offerId
        required: false
        schema:
          type: string
        style: form
      - description: filter by buyerId
        explode: true
        in: query
        name: buyerId
        required: false
        schema:
          type: string
        style: form
      - description: filter by externalId
        explode: true
        in: query
        name: externalId
        required: false
        schema:
          type: string
        style: form
      - description: filter by buyerAccountId is currently supported only for AWS
        explode: true
        in: query
        name: buyerAccountId
        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:
                items:
                  $ref: '#/components/schemas/WorkloadEntitlement'
                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 Entitlements
      tags:
      - Entitlement
    post:
      description: Create an new entitlement for the given buyer & offer. Only applicable to non cloud billing partners.
      operationId: CreateEntitlement
      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/CreateEntitlementParams'
        description: RequestBody
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          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: Create Entitlement
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}:
    get:
      description: Get the entitlement by ID.
      operationId: GetEntitlement
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          description: OK
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad request error
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not found
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal server error
      security:
      - APIKeyAuth: []
      summary: Get Entitlement
      tags:
      - Entitlement
  /org/{orgId}/entitlement/{entitlementId}/addCredit:
    post:
      description: Add the credit amount to the given Entitlement. The credit amount is accumulated & saved in the current Entitlement Term of the gvien Entitlement.
      operationId: AddEntitlementCredit
      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/AddEntitlementCreditParams'
        description: RequestBody
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddEntitlementCreditResponse'
          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: Add Entitlement Credit
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}/addon:
    post:
      description: Apply one billing addon to the given Entitlement. The entitlement status must be ACTIVE.
      operationId: ApplyAddonToEntitlement
      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/BillingAddonRecord'
        description: RequestBody
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          description: Entitlement
        '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: Apply Addon To Entitlement
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}/approve:
    post:
      description: Approve the given Entitlement. Only applicable to the Azure or GCP Entitlements with the status of "PENDING_START". Return 200 if the entitlement is already active.
      operationId: ApproveEntitlement
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          description: OK
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad request error
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not found
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal server error
      security:
      - APIKeyAuth: []
      summary: Approve Entitlement
      tags:
      - Entitlement
  /org/{orgId}/entitlement/{entitlementId}/cancel:
    post:
      description: Cancel the active subscription in Azure Marketplace.
      operationId: CancelEntitlement
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          description: the canceled Entitlement
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad request error
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not found
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal server error
      security:
      - APIKeyAuth: []
      summary: Cancel Entitlement
      tags:
      - Entitlement
  /org/{orgId}/entitlement/{entitlementId}/divideCommit:
    post:
      description: Divide the commit equally from the given entitlement into sub entitlement terms based on the given time periods.
      operationId: DivideEntitlementCommit
      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/DivideEntitlementCommitParams'
        description: RequestBody
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
          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: Divide Entitlement Commit
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}/entitlementName:
    patch:
      description: Update the name of the given Entitlement.
      operationId: UpdateEntitlementName
      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/github_com_sugerio_marketplace-service_pkg_legacy_rds-db_lib.UpdateEntitlementNameParams'
        description: UpdateEntitlementNameParams
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          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: Update Entitlement Name
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}/entitlementTerm:
    get:
      description: List all Entitlement Terms of the given Entitlement.
      operationId: ListEntitlementTerms
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WorkloadEntitlementTerm'
                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 Entitlement Terms
      tags:
      - Entitlement
  /org/{orgId}/entitlement/{entitlementId}/entitlementTerm/{entitlementTermId}:
    delete:
      description: Delete the entitlement term by the given entitlement ID and entitlement term ID. Only allow to delete the divided entitlement term.
      operationId: DeleteEntitlementTerm
      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
      - description: Entitlement Term ID
        explode: false
        in: path
        name: entitlementTermId
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
          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: Delete Entitlement Term
      tags:
      - Entitlement
    get:
      description: Get the entitlement term by ID.
      operationId: GetEntitlementTerm
      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
      - description: Entitlement Term ID
        explode: false
        in: path
        name: entitlementTermId
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlementTerm'
          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: Get Entitlement Term
      tags:
      - Entitlement
  /org/{orgId}/entitlement/{entitlementId}/metaInfo:
    patch:
      description: Update the meta info of the given entitlement.
      operationId: UpdateEntitlementMetaInfo
      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/WorkloadMetaInfo'
        description: Entitlement meta info to update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadMetaInfo'
          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: Update Entitlement Meta Info
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}/priceModel:
    patch:
      description: Update the price model of the given entitlement, such as recurring commits, billable dimensions. Only applicable to non cloud billing partners.
      operationId: UpdateEntitlementPriceModel
      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/UpdateEntitlementPriceModelParams'
        description: Entitlement price model update params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          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: Update Entitlement Price Model
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}/scheduleCancellation:
    post:
      description: Schedule the cancellation of the given Entitlement.
      operationId: ScheduleEntitlementCancellation
      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/CancellationSchedule'
        description: RequestBody
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          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: Schedule Entitlement Cancellation
      tags:
      - Entitlement
      x-codegen-request-body-name: data
  /org/{orgId}/entitlement/{entitlementId}/seat:
    patch:
      description: Update the seat number for the active AZURE subscription.
      operationId: UpdateEntitlementSeat
      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
      - description: New seat number
        explode: true
        in: query
        name: newSeat
        required: true
        schema:
          type: integer
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          description: the original entitlement before the seat update
        '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 Seat For The Active AZURE Subscription
      tags:
      - Entitlement
  /org/{orgId}/entitlement/{entitlementId}/unscheduleCancellation:
    post:
      description: Unschedule the cancellation of the given Entitlement.
      operationId: UnscheduleEntitlementCancellation
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadEntitlement'
          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: Unschedule Entitlement Cancellation
      tags:
      - Entitlement
components:
  schemas:
    AwsRenewalOfferType:
      enum:
      - ''
      - External
      - AwsMarketplace
      type: string
      x-enum-varnames:
      - AwsRenewalOfferType_Unknown
      - AwsRenewalOfferType_External
      - AwsRenewalOfferType_AwsMarketplace
    BillableDimension:
      example:
        priceModelTiered: '{}'
        priceModelTieredPercentage: '{}'
        priceModelMatrix: '{}'
        minimumCommit: 5.962133916683182
        length: 1
        priceModelBulk: '{}'
        description: description
        discount: '{}'
        minimumCommitScope: '{}'
        minimumCommitProrata: true
        billableMetricId: billableMetricId
        priceModelPercentage: '{}'
        name: name
        priceModelBasic: '{}'
        category: '{}'
        priceModelVolume: '{}'
        timeUnit: '{}'
      properties:
        billableMetricId:
          description: The ID for the billable metric.
          type: string
        category:
          allOf:
          - $ref: '#/components/schemas/PriceModelCategory'
          description: The category of the pricing model. This is used to determine which pricing model to use.
          type: object
        description:
          description: Description of the dimension. This is used in the UI to display the dimension.
          type: string
        discount:
          allOf:
          - $ref: '#/components/schemas/BillingDiscount'
          description: Discount for the dimension.
          type: object
        length:
          description: The term length for the commit amount. Applicable to Direct only.
          type: integer
        minimumCommit:
          description: The minimum commit amount. Applicable to Direct only. Ignored if the value is 0 or less.
          type: number
        minimumCommitProrata:
          description: 'If the minimum commit is appled with pro-rata. Applicable to Direct only.

            If true, the minimum commit amount will be prorated based on the usage period (starting time and ending time).'
          type: boolean
        minimumCommitScope:
          allOf:
          - $ref: '#/components/schemas/BillingMinimumCommitScope'
          description: The minimum commit scope. The default value is "DIMENSION" if not set.
          type: object
        name:
          description: Display name of the dimension. This is used in the UI to display the dimension.
          type: string
        priceModelBasic:
          allOf:
          - $ref: '#/components/schemas/PriceModelBasic'
          description: The configuration for the Basic pricing model. Applicable to Direct only.
          type: object
        priceModelBulk:
          allOf:
          - $ref: '#/components/schemas/PriceModelBulk'
          description: The configuration for the Package pricing model. Applicable to Direct only.
          type: object
        priceModelMatrix:
          allOf:
          - $ref: '#/components/schemas/PriceModelMatrix'
          description: The configuration for the Matrix pricing model. Applicable to Direct only.
          type: object
        priceModelPercentage:
          allOf:
          - $ref: '#/components/schemas/PriceModelPercentage'
          description: The configuration for the Percentage pricing model. Applicable to Direct only.
          type: object
        priceModelTiered:
          allOf:
          - $ref: '#/components/schemas/PriceModelTiered'
          description: The configuration for the Tiered pricing model. Applicable to Direct only.
          type: object
        priceModelTieredPercentage:
          allOf:
          - $ref: '#/components/schemas/PriceModelTieredPercentage'
          description: The configuration for the Tiered Percentage pricing model. Applicable to Direct only.
          type: object
        priceModelVolume:
          allOf:
          - $ref: '#/components/schemas/PriceModelVolume'
          description: The configuration for the Bulk pricing model. Applicable to Direct only.
          type: object
        timeUnit:
          allOf:
          - $ref: '#/components/schemas/TimeUnit'
          description: The term unit for the commit amount. Applicable to Direct only.
          type: object
      type: object
    client.DescribeInstanceResponseBodyModules:
      example:
        Module:
        - Id: Id
          Properties:
            Property:
            - PropertyValues:
                PropertyValue:
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
              DisplayUnit: DisplayUnit
              Key: Key
              Name: Name
              ShowType: ShowType
            - PropertyValues:
                PropertyValue:
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
              DisplayUnit: DisplayUnit
              Key: Key
              Name: Name
              ShowType: ShowType
          Code: Code
          Name: Name
        - Id: Id
          Properties:
            Property:
            - PropertyValues:
                PropertyValue:
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
              DisplayUnit: DisplayUnit
              Key: Key
              Name: Name
              ShowType: ShowType
            - PropertyValues:
                PropertyValue:
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
                - Type: Type
                  Min: Min
                  Max: Max
                  DisplayName: DisplayName
                  Value: Value
                  Step: Step
                  Remark: Remark
              DisplayUnit: DisplayUnit
              Key: Key
              Name: Name
              ShowType: ShowType
          Code: Code
          Name: Name
      properties:
        Module:
          items:
            $ref: '#/components/schemas/client.DescribeInstanceResponseBodyModulesModule'
          type: array
      type: object
    SnowflakeMarketplaceOffer:
      properties:
        access_end_time:
          type: string
        access_start_date_preference

# --- truncated at 32 KB (208 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suger/refs/heads/main/openapi/suger-entitlement-api-openapi.yml