query entitlements

GET https://api.suger.cloud/org/{orgId}/entitlement/query

Query entitlements with filtering, sorting, and pagination using CRUD query language. Supports complex filters, sorting by multiple fields, and pagination.

Parameters

Name	In	Type	Required	Description
`orgId`	path	string	yes	Organization ID
`page_size`	query	integer	no	Number of items per page (default 20, max 1000)
`page_number`	query	integer	no	Page number (default 1)
`q`	query	string	no	LISP-style filter expression (e.g., '(= status \
`s`	query	string	no	Sort fields: 'field:asc,field2:desc' or '-field,field2' format (e.g., 'creation_time:desc,product_id:asc' or '-creation_time,product_id')

Responses

200 — Paginated list of entitlements

Content-Type: application/json · Schema: crud.ListBaseResponse-orm_WorkloadEntitlement

crud.ListBaseResponse-orm_WorkloadEntitlement fields:

Field	Type	Required
`data`	array<orm.WorkloadEntitlement>	no
`page_number`	integer	no
`page_size`	integer	no
`total_count`	integer	no

orm.WorkloadEntitlement fields:

Field	Type	Required	Description
`buyerID`	string	no	BuyerID holds the value of the "buyer_id" field.
`creationTime`	string	no	CreationTime holds the value of the "creation_time" field.
`endTime`	string	no	EndTime holds the value of the "end_time" field.
`entitlementTermID`	string	no	EntitlementTermID holds the value of the "entitlement_term_id" field.
`externalBuyerID`	string	no	ExternalBuyerID holds the value of the "external_buyer_id" field.
`externalID`	string	no	ExternalID holds the value of the "external_id" field.
`externalProductID`	string	no	ExternalProductID holds the value of the "external_product_id" field.
`externalStatus`	string	no	ExternalStatus holds the value of the "external_status" field.
`id`	string	no	ID of the ent.
`info`	EntitlementInfo	no
`lastUpdateTime`	string	no	LastUpdateTime holds the value of the "last_update_time" field.
`metaInfo`	WorkloadMetaInfo	no
`name`	string	no	Name holds the value of the "name" field.
`offerID`	string	no	OfferID holds the value of the "offer_id" field.
`organizationID`	string	no	OrganizationID holds the value of the "organization_id" field.
`partner`	string	no	Partner holds the value of the "partner" field.
`partnerID`	string	no	PartnerID holds the value of the "partner_id" field.
`productID`	string	no	ProductID holds the value of the "product_id" field.
`service`	string	no	Service holds the value of the "service" field.
`startTime`	string	no	StartTime holds the value of the "start_time" field.
`status`	string	no	Status holds the value of the "status" field.
`type`	string	no	Type holds the value of the "type" field.

EntitlementInfo fields:

Field	Type	Required	Description
`addons`	array<BillingAddonRecord>	no	The addons for the entitlement.
`alertDaysBeforeEnd`	integer	no	Alert days before the end of the entitlement
`alibabaEntitlements`	array<client.DescribeInstanceResponseBody>	no	Nullable. Alibaba Entitlements from Alibaba Marketplace.
`alibabaOrders`	array<client.DescribeOrderResponseBody>	no	Nullable. Alibaba Orders from Alibaba Marketplace.
`annualizedAmount`	number	no	AnnualizedAmount is the recurring contract value normalized to one year in Currency. Analytics converts this snapshot to USD before aggregation. A nil value means that the entitlement is usage-based, one-time, or cannot be annualized from authoritative contract terms. It is copied into entitlement-term snapshots so historical SaaS metrics do not depend on invoice frequency or payment timing.
`autoRenew`	boolean	no	Is this Entitlement Auto Renew enabled.
`awsAgreement`	AwsMarketplaceAgreementV2	no
`awsAgreementPdfURL`	string	no	AwsAgreementPdfURL is the S3 URL of the AWS Marketplace Agreement PDF.
`awsChannelPartner`	AwsChannelPartner	no
`awsEntitlements`	array<TypesEntitlement>	no	Nullable. AWS Entitlements from AWS Marketplace.
`awsLicenseArn`	string	no	AwsLicenseArn for AWS concurrent agreement support
`awsOfferSetId`	string	no	AwsOfferSetID is the AWS Marketplace OfferSet Id, available for agreements originated from an offer associated with an offerSet.
`azureAssetID`	string	no	AzureAssetID is the Azure CMA AssetId (order identifier) for this entitlement. For VM offers, this differs from Entitlement.ExternalID (which stores ReferenceId for Metered Usage matching). Revenue matching uses this field as a fallback when ExternalID lookup fails.
`azureSubscriptions`	array<AzureMarketplaceSubscription>	no	Nullable. Azure Subscriptions from Azure Marketplace.
`billableDimensions`	array<BillableDimension>	no	The dimensions for billable metric usage-based metering. It's for Suger(Stripe, Ayden) metering.
`billingCycle`	BillingCycle	no
`billingIntervalInMonths`	integer	no	The billing interval from the offer.
`buyerManagementURL`	string	no	The buyer's management URL in the cloud marketplace. For different cloud marketplaces, the buyer management URL maybe different.
`collectableAmount`	number	no	The amount that the seller can collect. It excludes the marketplace commision fee.
`commitAmount`	number	no	The amount that the buyer has committed to pay. It can be the sum of payment installments if applicable.
`commits`	array<CommitDimension>	no	The dimensions for flatrate commitment (recurring or one-time).
`currency`	string	no	The default Currency is USD.
`deliveryMethod`	OfferDeliveryMethod	no
`dimensions`	array<MeteringDimension>	no	The dimensions for usage-based metering. It's for usage metering in cloud marketplaces. The max size of dimensions is 50. The oversized dimensions won't be saved in the EntitlementInfo. But the dimensions can be accessed from the connected offer info or product info.
`dimensionsOversized`	boolean	no	Whether the upper metering dimensions are oversized (exceed the max size 50).
`disbursedAmount`	number	no	The amount that has been disbursed to the seller account.
`eulaType`	EulaType	no
`eulaUrl`	string	no
`fallbackFromOffer`	boolean	no	A flag indicates that the current entitlement info is from offer (private or default/public), not awsAgreementTerms from AWS Marketplace.
`gcpEntitlements`	array<GcpMarketplaceEntitlement>	no	Nullable. GCP Entitlements from GCP Marketplace.
`gcpPlans`	array<GcpMarketplaceProductPurchaseOptionSpec>	no	Only applicable for GCP Marketplace Entitlements.
`gracePeriodInDays`	integer	no	The grace period for the offer. It is same as the TrialConfig in DirectOfferInfo. But can be overridden at the entitlement level.
`grossAmount`	number	no	The gross amount that the buyer has committed to pay, including usage metered amount.
`invoicedAmount`	number	no	The amount that the buyer has got invoiced.
`isMeteringOverageCommit`	boolean	no	Whether the usage metering will be charged for the amount that exceeds the committed amount from the offer.
`netTermsInDays`	integer	no	The net terms for the offer. It is same as the TrialConfig in DirectOfferInfo. But can be overridden at the entitlement level.
`offerVisibility`	OfferVisibility	no
`oracleAcceptedOffer`	OracleMarketplaceOffer	no
`paymentInstallments`	array<PaymentInstallment>	no	For flexible payment schedules
`paymentSchedule`	PaymentScheduleType	no
`refundCancellationPolicy`	string	no
`sellerNotes`	string	no
`snowflakeOffer`	SnowflakeMarketplaceOffer	no
`spaUrl`	string	no	The URL with JWT as auth method for the entitlement SPA. It can be shared with the buyer to access the SPA without login.
`trialConfig`	TrialConfig	no
`vendorName`	string	no	VendorName is the name of the vendor/manufacturer of the product. It is populated from the product metadata (e.g., aws_marketplace_manufacturer_name attribute or AwsProduct.Description.Manufacturer).

WorkloadMetaInfo fields:

Field	Type	Required	Description
`aceApnCrmUniqueIdentifier`	string	no	The linked ACE ApnCrmUniqueIdentifier of the private offer if available.
`approvalInfo`	ApprovalInfo	no
`awsSaasProductDimensions`	array<AwsProductDimension>	no	The AWS SaaS product dimensions. Applicable for AWS SaaS products only. This is used to save price info when creating AWS SaaS product.
`azureBillingAccountID`	string	no	The Azure billing account ID of the buyer for this entitlement. It is populated when syncing Azure private offers or subscriptions.
`azureOriginalOfferIDForUpgrade`	string	no	Original offer ID for Azure Upgrade
`baseAgreementId`	string	no	Applicable for AWS Marketplace only, when the IsAgreementBasedOffer is true.
`buyerCommitQuantities`	object	no	Buyer-supplied per-commit quantities used when accepting a ConfigurableUpfront AWS offer. Keyed by commit dimension key. Only set on offers where at least one commit allows buyer quantity configuration. Consumed by the chromedp accept flow to fill AWS's Unit configuration inputs before clicking Accept. Offer-scoped: it stays on the offer as the accept-time record and is stripped from entitlement transfer by CleanForTransfer.
`buyerIds`	array<string>	no	The Suger buyer IDs of the private offer if available.
`chargebeeSubscriptionID`	string	no	The Chargebee subscription ID of the private offer if available.
`contacts`	array<Contact>	no	The contacts of the offer to notify if any updates.
`cppoInOfferId`	string	no	The Suger CPPO_IN offer ID.
`cppoOfferId`	string	no	The Suger CPPO offer ID. Reseller to end buyer
`cppoOutOfferId`	string	no	The Suger CPPO_OUT offer ID. ISV to reseller
`createRetryAttempts`	integer	no	CreateRetryAttempts counts the out-of-process create retries scheduled for this offer after the partner worker's own in-process retries were exhausted with a retryable failure. Server-owned and bounded; see partner/gcp/marketplace_offer_retry_temporal.go for the delay ladder and PE-11626 for the background. Currently written only by the GCP create path.
`createdByEmail`	string	no	The email address of the user who created the offer. This field is immutable after creation. Especially useful for offers created from Salesforce/HubSpot integrations where the creator may not have a Suger account yet.
`createdBySource`	CreatedBySource	no
`customMetaInfo`	object	no	The custom meta info of the offer can be updated by seller via API or console.
`discount`	number	no	Discount is the private offer's uniform discount percentage relative to the product's public/list price, in 0-100 (e.g. 20 means the negotiated per-dimension rate is 20% off list), matching the Azure / GCP / DiscountGroup convention. AWS-only: unlike Azure percentage / GCP offers, AWS stores only absolute rates, so Suger persists this percentage so a later product list-price change can be re-applied to the private offer as listRate*(1-Discount/100). Set by the caller in the create-offer or updateMetaInfo request (or a backfill script); nil when unset (offer is skipped by discount propagation). A future per-dimension discount map can be added alongside this field, falling back to it.
`dynamics365OpportunityId`	string	no	Microsoft Dynamics 365 opportunity GUID (lowercased, no braces) linked to this offer. Persisted into workload_offer.meta_info JSONB; filtered by the dynamics365OpportunityId query parameter on the offer/entitlement list endpoints. Additive to SalesforceOpportunityId / HubspotDealId — an offer may carry any combination of the three.
`enableTestUsageMetering`	boolean	no	If enabled, Suger will test metering the usage for this entitlement hourly.
`entitlementCancellationSchedule`	CancellationSchedule	no
`errorMessages`	array<string>	no	The error messages when the offer is invalid or offer related tasks failed. This is the raw error messages from the offer related tasks.
`gcpBillingAccountID`	string	no	The GCP billing account ID of the buyer for this entitlement. It is populated when syncing GCP Marketplace entitlements.
`hubspotDealId`	string	no	Hubsport deal ID of the private offer if available.
`internalNote`	string	no	The Internal note of the private offer. It is only visible to the seller/ISV, not visible to the buyer. Up to MaxInternalNoteLength characters.
`isAgreementBasedOffer`	boolean	no	Applicable for AWS Marketplace only, If this offer is agreement based offer.
`isAzureUpgradeOffer`	boolean	no	If this offer is an Azure upgrade offer.
`isGrossRevenueFullSync`	boolean	no	Whether the gross revenue is fully synced for the entitlement.
`isRenewalOffer`	boolean	no	Applicable for AWS Marketplace only. If this offer is renewal offer of existing agreement. The existing agreement can be within or outside AWS Marketplace. AWS may audit and verify your offer is a renewal. If AWS is unable to verify your offer, then AWS may revoke the offer and entitlements from your customer.
`isReplacementOffer`	boolean	no	If this offer is a GCP replacement offer. Applicable for GCP Marketplace replacement offer only.
`lastModifiedBy`	LastModifiedBy	no
`nextCreateRetryAt`	string	no	NextCreateRetryAt is when the requeue Temporal workflow will resubmit the SQS create message. It is set only while the offer is PENDING_CREATE with a retry in flight, and is what distinguishes "still retrying" from a fresh submit; it is cleared once the offer is created, gives up, or the retry is abandoned. Best-effort: a terminated or timed-out requeue workflow can leave it stale, so treat Temporal as the source of truth.
`notifications`	array<NotificationEvent>	no	The notifications of the offer if any updates. In most cases, it is to notify contacts/buyers when the offer is pending acceptance.
`offerAcceptDate`	string	no	The date when the offer is accepted by the buyer. Only available when the private offer has been accepted.
`offerCreationSuccessDate`	string	no	The datetime when the offer was successfully created on the partner's marketplace (AWS, Azure, GCP, etc).
`orbAppliedCreditLedgerEntries`	object	no	Map of Orb credit ledger entry ID -> applied dollar amount, used to dedup usage-driven credit decrements already mirrored into the entitlement term credit (Orb credit netting). Written via targeted jsonb_set on the orbAppliedCreditLedgerEntries.{entryId} sub-key only — never full meta_info replace (cross-service JSONB rule). UpdateEntitlementMetaInfo retains it from the current row for the same reason: losing a key re-applies that decrement and double-credits the buyer, silently under-reporting usage to the cloud marketplace.
`originalEulaInfo`	OriginalEulaInfo	no
`prettifiedErrorMessages`	array<string>	no	The prettified ErrorMessages. Using AI to make it more readable and understandable. The prettified error messages will be used for the offer related UI display.
`privatePlans`	object	no	PrivatePlans is Suger-owned CRM metadata for the product's private plans, keyed by the plan externalId. Plans themselves live in Info.AzureProductResource.Plans (partner-synced); CRM metadata must live here so a partner sync cannot clobber it. Only used on products. Written via targeted jsonb_set on the privatePlans.{planExternalId} sub-key only — never full meta_info replace (cross-service JSONB rule).
`renewalOfferType`	AwsRenewalOfferType	no
`replacedOfferEndTime`	string	no	The end time of the replaced offer. Applicable for GCP Marketplace replacement offer only.
`replacedOfferPaymentRecurrence`	string	no	The payment recurrence of the replaced (base) offer, captured when the replacement draft is saved. The draft edit page rebuilds the allowed payment-recurrence options from it, since that page navigates without an entitlement and cannot re-derive the base cadence. Applicable for GCP Marketplace replacement offer only.
`replacedOfferResourceName`	string	no	The resource name of the GCP Marketplace offer that this offer is replacing. In format of "projects/{gcpProjectNumber}/services/{productServiceName}/privateOffers/{privateOfferId}" Applicable for GCP Marketplace replacement offer only.
`replacedResellerPrivateOfferPlan`	string	no	The resource name of the GCP marketplace reseller private offer plan that this offer is replacing. In format of "resellerPrivateOfferPlans/{resellerOfferPrivatePlanId}"
`resellerIds`	array<string>	no	The reseller IDs (in the identity.buyer table) associated with this offer. Only applicable for CPPO_OUT & CPPO offers.
`salesforceAccountId`	string	no	The Salesforce account ID directly linked to the private offer if available. Lets a user associate an offer with a Salesforce Account without going through an opportunity. Surfaced alongside opportunity-linked offers in the Salesforce app's account insights panel (AccountController.getActiveAndAcceptedOffersForAccount).
`salesforceEntitlementURL`	string	no	The Salesforce entitlement URL
`salesforceOpportunityId`	string	no	The Salesforce opportunity ID of the private offer if available.
`salesforceQuoteId`	string	no	The Salesforce Quote ID of the private offer if available.
`sourceOfferCancelAfterPublishAt`	string	no	SourceOfferCancelAfterPublishAt is the time the source-offer cancellation was last attempted.
`sourceOfferCancelAfterPublishError`	string	no	SourceOfferCancelAfterPublishError is the error/skip reason recorded when the source-offer cancellation did not succeed. Internal audit field.
`sourceOfferCancelAfterPublishStatus`	string	no	SourceOfferCancelAfterPublishStatus tracks the outcome of the source-offer cancellation triggered after this offer reached PENDING_ACCEPTANCE: "" (not attempted), "PENDING", "SENT", "SKIPPED" or "FAILED". Internal audit field; not shown to buyers.
`sourceOfferIdToCancelAfterPublish`	string	no	SourceOfferIdToCancelAfterPublish is the Suger offer ID of the source GCP private offer that should be cancelled once this (cloned) offer reaches PENDING_ACCEPTANCE. Set by the console clone flow; consumed by the GCP create-response sync. Applicable for GCP Marketplace clone-and-cancel offers only.
`testUsageMeteringEndTime`	string	no	The test usage metering end time. It is used for test usage metering only. Required if EnableTestUsageMetering is true.
`updateMessage`	string	no	The message to notify when the offer is updated.
`warningMessages`	array<string>	no	Warning messages for non-blocking issues that were auto-fixed. For example, deal type auto-fix when Native Renewal eligibility criteria are not met.

BillingAddonRecord fields:

Field	Type	Required
`amount`	number	no
`chargeOn`	string	no
`description`	string	no
`id`	string	no
`name`	string	no

client.DescribeInstanceResponseBody fields:

Field	Type	Required	Description
`ActiveAddress`	string	no
`AppJson`	string	no	example: {"frontEndUrl":"https://**.aliyundoc.com","password":"Sjtv","adminUrl":"https://*.aliyundoc.com","username":"aliyun*"}
`AutoRenewal`	string	no
`BeganOn`	integer	no	example: 1570634021000
`ComponentJson`	string	no	example: {"package_version":"yuncode000111"}
`Constraints`	string	no	example: {}
`CreatedOn`	integer	no	example: 1570634018000
`EndOn`	integer	no	example: 1602259200000
`ExtendJson`	string	no
`HostJson`	string	no	example: {"password":"*","ip":"118.31..41","innerIp":"118.31..41","region":"","username":"*","beianInfo":""}
`InstanceId`	integer	no	example: 1551111111
`IsTrial`	boolean	no	example: true
`LicenseCode`	string	no
`Modules`	client.DescribeInstanceResponseBodyModules	no
`OrderId`	integer	no	example: 204211111111111
`ProductCode`	string	no	example: cmgj00**11
`ProductName`	string	no
`ProductSkuCode`	string	no	example: cmgj00**11-prepay
`ProductType`	string	no	example: APP
`RelationalData`	client.DescribeInstanceResponseBodyRelationalData	no
`Status`	string	no	example: OPENED
`SupplierName`	string	no

client.DescribeOrderResponseBody fields:

Field	Type	Required	Description
`AccountQuantity`	integer	no	example: 0
`AliUid`	integer	no	example: 190311111111****
`Components`	object	no
`CouponPrice`	number	no	example: 0.0
`CreatedOn`	integer	no	example: 1531191564000
`InstanceIds`	client.DescribeOrderResponseBodyInstanceIds	no
`OrderId`	integer	no	example: 202211111111111
`OrderStatus`	string	no	example: NORMAL
`OrderType`	string	no	example: NEW
`OriginalPrice`	number	no	example: 10.0
`PaidOn`	integer	no	example: 1531191675000
`PayStatus`	string	no	example: PAID
`PaymentPrice`	number	no	example: 0.0
`PeriodType`	string	no	example: MONTH
`ProductCode`	string	no	example: cmgj02****
`ProductName`	string	no
`ProductSkuCode`	string	no	example: cmgj02****-prepay
`Quantity`	integer	no	example: 1
`RequestId`	string	no	example: 6EF60BEC-0242-43AF-BB20-270359FB54A7
`SupplierCompanyName`	string	no
`SupplierTelephones`	client.DescribeOrderResponseBodySupplierTelephones	no
`TotalPrice`	number	no	example: 0.0

AwsMarketplaceAgreementV2 fields:

Field	Type	Required	Description
`acceptanceTime`	string	no
`agreementId`	string	no	AWS Marketplace Agreement Id
`agreementType`	string	no
`buyerAccountId`	string	no	The AWS Account Id of the buyer in AWS Marketplace
`endTime`	string	no
`licenseArn`	string	no	AWS License Manager license ARN associated with this agreement (Concurrent Agreement support).
`offerId`	string	no	AWS Marketplace Offer Id
`offerSetId`	string	no	AWS Marketplace OfferSet Id, available for agreements originated from an offer associated with an offerSet.
`productId`	string	no	AWS Marketplace Product Id
`productType`	string	no
`sellerAccountId`	string	no	The AWS Account Id of the seller in AWS Marketplace
`startTime`	string	no
`status`	AwsMarketplaceAgreementStatus	no

AwsChannelPartner fields:

Field	Type	Required	Description
`id`	string	no	The AWS Account ID of the Channel Partner
`name`	string	no	The name of the Channel Partner

TypesEntitlement fields:

Field	Type	Required	Description
`customerAWSAccountId`	string	no	The CustomerAWSAccountId parameter specifies the AWS account ID of the buyer.
`customerIdentifier`	string	no	The customer identifier is a handle to each unique customer in an application. Customer identifiers are obtained through the ResolveCustomer operation in AWS Marketplace Metering Service.
`dimension`	string	no	The dimension for which the given entitlement applies. Dimensions represent categories of capacity in a product and are specified when the product is listed in AWS Marketplace.
`expirationDate`	string	no	The expiration date represents the minimum date through which this entitlement is expected to remain valid. For contractual products listed on AWS Marketplace, the expiration date is the date at which the customer will renew or cancel their contract. Customers who are opting to renew their contract will still have entitlements with an expiration date.
`licenseArn`	string	no	The LicenseArn is a unique identifier for a specific granted license. These are used for software purchased through AWS Marketplace.
`productCode`	string	no	The product code for which the given entitlement applies. Product codes are provided by AWS Marketplace when the product listing is created.
`value`	types.EntitlementValue	no

AzureMarketplaceSubscription fields:

Field	Type	Required
`allowedCustomerOperations`	array<string>	no
`autoRenew`	boolean	no
`beneficiary`	AzureADIdentifier	no
`created`	string	no
`fulfillmentId`	string	no
`id`	string	no
`isFreeTrial`	boolean	no
`isTest`	boolean	no
`lastModified`	string	no
`name`	string	no
`offerId`	string	no
`planId`	string	no
`publisherId`	string	no
`purchaser`	AzureADIdentifier	no
`quantity`	integer	no
`saasSubscriptionStatus`	AzureMarketplaceSubscriptionStatus	no
`sandboxType`	string	no
`sessionId`	string	no
`sessionMode`	string	no
`storeFront`	string	no
`term`	AzureTerm	no

BillableDimension fields:

Field	Type	Required	Description
`billableMetricId`	string	no	The ID for the billable metric.
`category`	PriceModelCategory	no
`description`	string	no	Description of the dimension. This is used in the UI to display the dimension.
`discount`	BillingDiscount	no
`length`	integer	no	The term length for the commit amount. Applicable to Direct only.
`minimumCommit`	number	no	The minimum commit amount. Applicable to Direct only. Ignored if the value is 0 or less.
`minimumCommitProrata`	boolean	no	MinimumCommitProrata enables pro-rated minimum commit billing. Applicable to Direct only. If true, the minimum commit amount will be prorated based on the entitlement period. For example, if an entitlement is only active for 10 days of a monthly billing period, only 10/30 of the minimum commit amount will be charged.
`minimumCommitScope`	BillingMinimumCommitScope	no
`name`	string	no	Display name of the dimension. This is used in the UI to display the dimension.
`priceModelBasic`	PriceModelBasic	no
`priceModelBulk`	PriceModelBulk	no
`priceModelMatrix`	PriceModelMatrix	no
`priceModelPercentage`	PriceModelPercentage	no
`priceModelTiered`	PriceModelTiered	no
`priceModelTieredPercentage`	PriceModelTieredPercentage	no
`priceModelVolume`	PriceModelVolume	no
`timeUnit`	TimeUnit	no

400 — Bad request error

Content-Type: application/json

500 — Internal server error

Content-Type: application/json

View as Markdown · Interactive API reference

Spotted something wrong or out of date on this page? Tell us and we'll correct it.