OpenAPI Specification
openapi: 3.0.1
info:
contact:
email: support@suger.io
name: Suger Support
url: https://www.suger.io/support
description: CRUD operations on a set of resources, including organizations, products, offers, entitlements, usage record groups for meterting, etc.
title: Suger API 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:
AzureADIdentifier:
example:
firstName: firstName
lastName: lastName
licenseType: licenseType
puid: puid
customerId: customerId
tenantId: tenantId
billingAccountId: billingAccountId
emailId: emailId
objectId: objectId
properties:
billingAccountId:
description: Azure Billing Account ID
type: string
customerId:
type: string
emailId:
description: Email address
type: string
firstName:
type: string
lastName:
type: string
licenseType:
description: Azure License Type
type: string
objectId:
type: string
puid:
description: ID of the user, used as External ID of suger IdentityBuyer.
type: string
tenantId:
type: string
type: object
SnowflakeMarketplaceOffer:
properties:
access_end_time:
type: string
access_start_date_preference:
type: string
access_start_time:
type: string
additional_information:
type: string
comment:
type: string
contract_duration_months:
type: integer
contract_type:
type: string
contract_value:
type: string
discount:
type: number
display_name:
type: string
expiration_time:
type: string
invoice_start_date_preference:
description: 'invoice start date preference: FIRST_DAY_NEXT_MONTH, OFFER_ACCEPTED_DATE'
type: string
invoice_start_time:
type: string
is_default:
type: boolean
name:
type: string
payment_terms:
$ref: '#/components/schemas/SnowflakeMarketplaceOfferPaymentTerms'
pricing_plan_name:
type: string
state:
type: string
state_updated_on:
type: string
target_consumer:
type: string
terms_of_service:
allOf:
- $ref: '#/components/schemas/SnowflakeMarketplaceOfferTermsOfService'
description: 'terms of service: {"type":"DEFAULT"}'
type: object
updated_on:
type: string
type: object
AzureIncludedBaseQuantity:
example:
quantity: 1.2315135367772556
isInfinite: true
recurringUnit: Monthly
properties:
isInfinite:
type: boolean
quantity:
type: number
recurringUnit:
enum:
- Monthly
- Annual
type: string
type: object
SnowflakeMarketplacePlanInstallment:
example:
installment_amount: 4.652396432933246
installment_number: 8.969578798196912
properties:
installment_amount:
type: number
installment_number:
type: number
type: object
AzureMarketplaceSubscriptionStatus:
enum:
- NotStarted
- PendingFulfillmentStart
- Subscribed
- Suspended
- Unsubscribed
type: string
x-enum-varnames:
- AzureMarketplaceSubscriptionStatus_NotStarted
- AzureMarketplaceSubscriptionStatus_PendingFulfillmentStart
- AzureMarketplaceSubscriptionStatus_Subscribed
- AzureMarketplaceSubscriptionStatus_Suspended
- AzureMarketplaceSubscriptionStatus_Unsubscribed
PriceModelBulk:
properties:
bulkAmount:
description: A currency amount to rate usage by
type: number
bulkSize:
description: 'An integer amount to represent package size. For example, 1000 here would divide
usage by 1000 before multiplying by package_amount in rating'
type: integer
type: object
TrialConfig:
properties:
trialPeriod:
type: integer
trialPeriodUnit:
$ref: '#/components/schemas/TimeUnit'
type: object
NotificationEventAction:
enum:
- ''
- ABNORMAL_ALERT
- ACCEPT
- ADD
- APPROVE
- CANCEL
- CLOSE
- CREATE
- DELETE
- ARCHIVE
- DISBURSE
- END_SOON
- EXPIRE
- EXPIRE_SOON
- MERGE
- METER
- NEW_CLIENT_SIGNUP
- NOTIFY
- NOTIFY_CONTACTS
- OPEN_EMAIL
- PENDING_CANCEL
- PENDING_ACCEPTANCE
- REINSTATE
- REJECT
- REOPEN
- CHARGE
- REFUND
- ISSUE
- SIGN
- ROTATE_SECRET
- SUSPEND
- TEST
- UPDATE
- ACE_ENGAGEMENT_SCORE_UPDATE
- ACE_SALES_REP_UPDATE
- ACE_CUSTOMER_EMAIL_UPDATE
- AZURE_STATUS_UPDATE
- SUBMIT_APPROVAL_REQUEST
- REVIEW_APPROVAL_REQUEST
- COMPLETE
- FAIL
- WEBHOOK
- MARKETPLACE_CONTACT_EMAIL_UPDATE
type: string
x-enum-comments:
NotificationEventAction_ADD: Add user to organization
x-enum-varnames:
- NotificationEventAction_UNKNOWN
- NotificationEventAction_ABNORMAL_ALERT
- NotificationEventAction_ACCEPT
- NotificationEventAction_ADD
- NotificationEventAction_APPROVE
- NotificationEventAction_CANCEL
- NotificationEventAction_CLOSE
- NotificationEventAction_CREATE
- NotificationEventAction_DELETE
- NotificationEventAction_ARCHIVE
- NotificationEventAction_DISBURSE
- NotificationEventAction_END_SOON
- NotificationEventAction_EXPIRE
- NotificationEventAction_EXPIRE_SOON
- NotificationEventAction_MERGE
- NotificationEventAction_METER
- NotificationEventAction_NEW_CLIENT_SIGNUP
- NotificationEventAction_NOTIFY
- NotificationEventAction_NOTIFY_CONTACTS
- NotificationEventAction_OPEN_EMAIL
- NotificationEventAction_PENDING_CANCEL
- NotificationEventAction_PENDING_ACCEPTANCE
- NotificationEventAction_REINSTATE
- NotificationEventAction_REJECT
- NotificationEventAction_REOPEN
- NotificationEventAction_CHARGE
- NotificationEventAction_REFUND
- NotificationEventAction_ISSUE
- NotificationEventAction_SIGN
- NotificationEventAction_ROTATE_SECRET
- NotificationEventAction_SUSPEND
- NotificationEventAction_TEST
- NotificationEventAction_UPDATE
- NotificationEventAction_ACE_ENGAGEMENT_SCORE_UPDATE
- NotificationEventAction_ACE_SALES_REP_UPDATE
- NotificationEventAction_ACE_CUSTOMER_EMAIL_UPDATE
- NotificationEventAction_AZURE_STATUS_UPDATE
- NotificationEventAction_SUBMIT_APPROVAL_REQUEST
- NotificationEventAction_REVIEW_APPROVAL_REQUEST
- NotificationEventAction_COMPLETE
- NotificationEventAction_FAIL
- NotificationEventAction_WEBHOOK
- NotificationEventAction_MARKETPLACE_CONTACT_EMAIL_UPDATE
BillingDiscount:
example:
discountType: PERCENTAGE
value: 1.4658129805029452
properties:
discountType:
$ref: '#/components/schemas/BillingDiscountType'
value:
type: number
type: object
GcpMarketplacePriceModel:
enum:
- FREE
- SUBSCRIPTION
- USAGE
- S
# --- 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