Listing, buying, and licensing a product on AWS Marketplace programmatically

A complete, vendor-neutral reference for doing AWS Marketplace end-to-end through APIs instead of the console: assembling and publishing a container listing (Catalog API), buying it for testing (Discovery + Agreements APIs), and enforcing entitlement at runtime (License Manager or the Metering Service). Every operation, IAM permission, region constraint, and error mapping below is drawn from AWS documentation or confirmed against a live API run.

In short: which APIs do what

To operate an AWS Marketplace product programmatically you use four distinct services, not one:

• Catalog API (seller) — create and edit your listing through asynchronous change sets, and publish it (UpdateVisibility).
• Discovery API (buyer) — read offers and their terms to drive a purchase.
• Agreements API (buyer) — request and accept an agreement (the actual purchase), and inspect entitlements and charges.
• License Manager or Marketplace Metering Service (buyer runtime) — verify the customer is entitled, and (for usage pricing) meter usage. Which one is determined by your pricing model.

All AWS Marketplace API operations run in us-east-1.

Which service owns which operation?

Do I need AWS License Manager or the Marketplace Metering Service?

It is determined by product type × pricing model, not by preference — and wiring to the wrong service for your pricing model fails in production even when unit tests pass.

The two “not entitled” errors differ: the License Manager path returns NoEntitlementsAllowedException; the Metering Service path returns CustomerNotEntitledException. They are not interchangeable.

How do I list and update a product through the Catalog API?

Every seller-side change is an asynchronous change set against an entity (your product). The pattern is always: call StartChangeSet, get back a ChangeSetId, then poll DescribeChangeSet until it reaches a terminal status. Use DetailsDocument (native JSON); the older Details string form is legacy.

The change types you assemble a listing from:

• UpdateInformation— listing copy (title, descriptions, highlights, support info, logo, additional resources). This is a PATCH: any field you omit keeps its previous value, so a targeted copy edit cannot accidentally blank your highlights or logo.
• UpdateDimensions— entitlement dimensions. The payload is a bare array of {Key, Types, Name, Description}; Key+Types identify a row and Types is immutable once set.
• UpdatePricingTerms — replaces pricing terms in their entirety. You must restate every rate card, or you delete the ones you omit. Legal, Support, and Renewal terms have their own change types and are untouched by it.
• AddDeliveryOptions— ships a new product version plus its container delivery option (EcrDeliveryOptionDetails: container images, deployment resources, usage instructions ≤ 4000 characters).

Field limits worth pre-validating: Title ≤ 72, ShortDescription ≤ 1000, LongDescription ≤ 5000, Highlights ≤ 3, SearchKeywords ≥ 1 (≤ 250 combined characters), Categories ≤ 3. The ChangeSetName must match ^[\w\s+=.:@-]{1,100}$— note that parentheses are not allowed.

What are the change-set status values, and when can I cancel?

DescribeChangeSet returns one of: PREPARING → APPLYING → SUCCEEDED, or CANCELLED / FAILED (a FailureCode such as CLIENT_ERROR, plus per-change ErrorDetailList).

• A change set can be cancelled (CancelChangeSet) only while it is PREPARING.
• A single StartChangeSet accepts up to 20 changes across one or multiple entities; the same change type cannot repeat on one entity in one set.
• An entity is locked while a change set runs against it — a concurrent change returns ResourceInUseException (HTTP 423).

Container-listing rules that reject change sets

• Marketplace ECR holds plain Image Manifest V2 images only. Pushing Sigstore signatures, SLSA/attestation artifacts, or OCI referrer artifacts breaks it (UNSUPPORTED_CONTAINER_IMAGE_URI). Mirror the image by digest into Marketplace ECR; keep supply-chain artifacts on your public registry.
• No :latest or otherwise mutable tag is allowed; referenced images must live in Marketplace ECR, and usage instructions must deploy the Marketplace ECR image. (This is a documented policy; AWS does not surface it under a single named error code.)
• Usage instructions must be ASCII-only. An em-dash, smart quotes, or other Unicode triggers INVALID_USAGE_INSTRUCTIONS.
• Every AddDeliveryOptions triggers an automated layer scan — CVEs, malware, end-of-life OS/packages, hardcoded secrets, root user — and the change set fails if any are found. AWS also continuously re-scans public listings and can pull non-compliant products from new subscriptions.

How do I publish a Limited product to Public?

Publishing is a single UpdateVisibility change on the product with DetailsDocument: {"TargetVisibility": "Public"} — but it is the step AWS gates most heavily:

• It must be alone in its own change set, and it locks the product against all other change sets for the entire review window, so land all copy, version, and pricing changes first.
• It triggers a manual Seller-Ops review of up to 37 days. The change set can be cancelled while it is still PREPARING, before the audit begins; a failed review returns AUDIT_ERROR. (AWS documents an explicit 24-hour change-your-mind window specifically for the Restrict transition.)
• Pre-check: a public seller profile must exist on the account, or the change fails with MISSING_SELLER_PROFILE_INFORMATION.
• Once public: a 90-day price-increase lock applies, and existing delivery options freeze (version title, container images, delivery-option title, deployment resources) — add a new version rather than editing a published one.

The review checks copy completeness, logo, EULA and refund policy, real pricing, usage instructions that actually work end-to-end, and License Manager integration behavior. Because that last point is verified against a real purchase, it pays to test the buyer experience before submitting (next section).

How do I buy or test my own listing programmatically (no console)?

A seller can subscribe to its own Limited-visibility product (proposer and acceptor on the same account works), which is the supported way to test the full purchase-and-entitlement path. The documented cheap-test pattern: keep the product Limited, drop every rate card to $0.01 with one UpdatePricingTerms change set, buy it, validate, then restore the exact original pricing (save the full original terms JSON and re-apply it, since UpdatePricingTerms replaces wholesale).

The buyer flow combines Discovery (read) and Agreements (purchase):

1. GetOffer(offerId) (Discovery) → the agreementProposalId (at-…), seller of record, pricing model.
2. GetOfferTerms(offerId)(Discovery) → the term IDs (pricing, legal, support, renewal) and live rate cards.
3. CreateAgreementRequest({ intent: 'NEW', agreementProposalIdentifier, requestedTerms: [...] }) (Agreements) → an agreementRequestId (ar-…) and a chargeSummary that shows the exact charge before you commit. The pricing term carries the selected duration and dimension quantity; legal/support terms are accepted bare; the renewal term sets auto-renew.
4. AcceptAgreementRequest({ agreementRequestId }) (Agreements) → the agreementId (agmt-…). This is the point money moves.

What is the readiness signal after purchase?

Poll GetAgreementEntitlements (Agreements API) until it reports PROVISIONED — typically about 90 seconds; the agreement itself is ACTIVE immediately on accept. Do not poll the seller-side marketplace-entitlement get-entitlements, which can lag much longer and make a ready entitlement look absent. The License Manager license and grant appear shortly after PROVISIONED.

A fresh buyer account also needs the License Manager service-linked role before any checkout succeeds, or every call fails with “Service role not found”:

aws iam create-service-linked-role --aws-service-name license-manager.amazonaws.com

How do I check entitlement at runtime (contract pricing / License Manager)?

For a container product with contract pricing, your software calls CheckoutLicense at startup to prove the running customer bought it. The semantics that trip up most integrations:

• ProductSKU is the product ID (prod-…), not the product code (eq9fe4…). The issued license carries the product ID in its ProductSKU, and CheckoutLicense matches on it. AWS states this in one parenthetical: “the application's Product SKU (Product ID).”
• Match CheckoutType to the license. A floating/tiered contract license — configured with a ProvisionalConfiguration (e.g. a 60-minute MaxTimeToLiveInMinutes), the common entitlement-check pattern — checks out with PROVISIONAL; a drawdown/consumption license uses PERPETUAL. Checking out a floating license with PERPETUAL returns NoEntitlementsAllowedException, so match the type to the license's configuration.
• The entitlement is counted. Send the entitlement as { Name: '<dimension>', Unit: 'Count', Value: '1' } (the Value is required).
• The ClientToken must be fresh per attempt (randomUUID()). License Manager accepts a token once, then rejects every reuse for the rest of the UTC day — across processes. The SDK already reuses the token across its internal retries of a single send, which is the token's only job.
• Check the license back in immediately. A successful checkout consumes the counted unit for the provisional TTL, so a second replica or a restart within the hour would get NoEntitlementsAllowed. Call CheckInLicense right after validating, and use the result purely as an entitlement probe rather than a seat lock. The license is not node-bound: any container on any node with the right credentials can check it out.
• Expiration in the response is the token TTL, not the contract end. Read the contract validity from the license's Validity (Begin/End) via GetLicense; mapping Expiration to “licensed through” displays an expiry of today on every install.

Runtime IAM needs license-manager:CheckoutLicense, CheckInLicense, GetLicense, ListReceivedLicenses, and ExtendLicenseConsumption(the last extends a floating checkout past its TTL), with credentials supplied by the runtime (ECS task role, EKS IRSA, or instance profile) — never baked into the image.

How do I check entitlement at runtime (usage pricing / Metering Service)?

For usage or hourly pricing, the Metering Service both verifies entitlement and meters usage:

• Use RegisterUsage for hourly and fixed-monthly pricing (AWS meters automatically) and MeterUsage for custom dimensions you price yourself. Not-entitled returns CustomerNotEntitledException (a RegisterUsage call at container startup may instead return CustomerNotSubscribedException).
• Do not configure a static region — the call must run in the task's launch region (obtain it at runtime), or you get InvalidRegionException.
• Integrate metering into the running software, not the image CMD/ENTRYPOINT, so buyers who can insert image layers cannot override it. If product codes are passed via overridable config (CloudFormation, Helm, manifests), maintain a trusted product-code allowlist.
• Calls only work on AWS container services; local development raises PlatformNotSupportedException.

What IAM permissions does each side need?

Seller (Catalog API): the AWSMarketplaceSellerFullAccess managed policy (full Catalog write) or AWSMarketplaceSellerProductsReadOnly (read-only). For least privilege, grant aws-marketplace:StartChangeSet on the entity ARN plus a ChangeSet ARN with a /* wildcard (a fresh change-set ID is minted per request, so the wildcard is required), and optionally scope by change type with the catalog:ChangeType condition key. Resource-level permissions for StartChangeSet work only through the Catalog API, not the Management Portal console.

Buyer (procurement): the aws-marketplace:* agreement/discovery actions (e.g. CreateAgreementRequest, AcceptAgreementRequest).

Buyer (runtime): for contract products, license-manager:CheckoutLicense, CheckInLicense, GetLicense, ListReceivedLicenses, and ExtendLicenseConsumption, plus the License Manager service-linked role; for usage products, the metering actions.

Error reference: what each Marketplace error actually means

AWS Marketplace errors are terse and often overloaded onto one string. The mappings:

FAQ

Sources

• AWS Marketplace API Reference
• Using the AWS Marketplace Catalog API — change-set workflow, status values, ≤ 20 changes/set
• Access control for the Catalog API — IAM managed policies, granular StartChangeSet, catalog:ChangeType condition key
• Actions, resources, and condition keys for AWS Marketplace Catalog — Service Authorization Reference
• Using the AWS Marketplace Discovery API — the 9 operations
• Using the AWS Marketplace Agreement API
• AWS Marketplace now supports programmatic procurement with Agreements API — May 2026
• Container product billing, metering, and licensing integrations — the decision matrix; region-at-runtime; license-not-node-bound
• Contract pricing for container products with AWS License Manager — the “Product SKU (Product ID)” parenthetical; floating licenses; buyer IAM
• Getting started with container products — Limited visibility, $0.01 test pricing, layer scan, going Public
• Marketplace Metering Service API reference — RegisterUsage, MeterUsage, BatchMeterUsage