AWS marketplace: Document subsidiary authorization offers in AWS Marketplace
Summary
Adds documentation for creating private offers and replacement offers using subsidiary authorizations, including new change types (CreateOfferUsingSubsidiaryAuthorization, CreateReplacementOfferUsingSubsidiaryAuthorization), validation rules, and re-validation of authorization scope at release time.
Security assessment
The change documents an authorization-scoping feature: offers are constrained to the current subsidiary authorization, re-validated at release, and denied with AccessDeniedException when the account lacks permission. This is security-relevant authorization guidance but does not address a specific vulnerability or incident.
Evidence
AWS Marketplace re-validates the offer against the subsidiary authorization when you publish it with `ReleaseOffer`. If the primary account revoked or narrowed the authorization after you created the offer, the release fails.
Diff
diff --git a/marketplace/latest/developerguide/work-with-private-offers.md b/marketplace/latest/developerguide/work-with-private-offers.md index e8150cb..acadf74 100644 --- a//marketplace/latest/developerguide/work-with-private-offers.md +++ b//marketplace/latest/developerguide/work-with-private-offers.md @@ -27,0 +28,13 @@ There are two types of offers: +An offer can originate in one of three ways: + + * **Direct** – The seller that owns the product creates the offer. For more information, see Create an offer. + + * **From a resale authorization** – An AWS Marketplace Channel Partner creates the offer using a selling authorization granted by an independent software vendor (ISV). For more information, see [Create a CPPO](./work-with-cppos.html#create-offer-using-resale-auth). + + * **From a subsidiary authorization** – One of a seller's own AWS Marketplace seller accounts creates the offer using an authorization granted by the account that owns the product. For more information, see Create an offer using a subsidiary authorization. + + + + +In every case, the account that creates the offer is the seller of record on that offer. That account sets its own pricing, is charged AWS Marketplace fees on its own account, and receives disbursement to its own bank account. + @@ -80 +93 @@ You can use the Catalog API to create a new offer in AWS Marketplace. If your re -To create a new offer, call the `StartChangeSet` API operation with the `CreateOffer` change type, as shown in the following example. +To create a new offer for a product that your own account owns, call the `StartChangeSet` API operation with the `CreateOffer` change type, as shown in the following example. To create a new private offer for a product that another of your organization's accounts has authorized you to sell, see Create an offer using a subsidiary authorization. @@ -186,0 +200,127 @@ INCOMPATIBLE_PRODUCT | **`CreateOffer change type can't be invoked to create an +### Create an offer using a subsidiary authorization + +You can use the Catalog API to create a private offer for a product that your organization's primary account has authorized you to sell through a subsidiary authorization. To learn more about subsidiary authorizations, see [Work with subsidiary authorizations using the AWS Marketplace APIs](./work-with-subsidiary-authorizations.html). + +Creating the offer takes two steps: find the subsidiary authorization for the product you want to sell, then use its ID to create the offer. As with `CreateOffer`, the offer is created in `Draft` state. Use the `Update` change types on this page to complete it, then use the ReleaseOffer change type to publish it. + +**Step 1: Get your subsidiary authorization ID** + +To create the offer, you need the ID of an `Active` subsidiary authorization that targets your account. To find it, call the `[ListEntities](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_ListEntities.html)` API operation with `EntityType` set to `SubsidiaryAuthorization`. When you call it from a subsidiary account, the response contains only the active authorizations shared with your account. For the full list of filters and sort options, see [List your subsidiary authorizations](./work-with-subsidiary-authorizations.html#list-subsidiary-authorizations). + + + POST /ListEntities HTTP/1.1 + Content-type: application/json + + { + "Catalog": "AWSMarketplace", + "EntityType": "SubsidiaryAuthorization", + "EntityTypeFilters": { + "SubsidiaryAuthorizationFilters": { + "Status": { "ValueList": ["Active"] } + } + } + } + +The response looks like the following. + + + { + "EntitySummaryList": [ + { + "Name": "Test Subsidiary Authorization", + "EntityType": "SubsidiaryAuthorization", + "EntityId": "subauthz-1a2bexample34", + "EntityArn": "arn:aws:aws-marketplace:us-east-1:111122223333:AWSMarketplace/SubsidiaryAuthorization/subauthz-1a2bexample34", + "LastModifiedDate": "2026-10-26T21:21:07Z", + "SubsidiaryAuthorizationSummary": { + "Status": "Active", + "ResourceId": "prod-3c4dexample12", + "ResourceName": "Test SaaS Product", + "SubsidiaryAccountId": "444455556666", + "CreatedDate": "2026-10-26T21:15:47.88Z" + } + } + ], + "NextToken": "abcdabcd-wxyz-pqrs-lmno-defgdefgdefg" + } + +Find the entry whose `SubsidiaryAuthorizationSummary.ResourceId` is the product you want to sell, and use its `EntityId` as the `SubsidiaryAuthorizationId` in step 2. + +**Step 2: Create the offer** + +To create a new private offer using a subsidiary authorization, call the `StartChangeSet` API operation with the `CreateOfferUsingSubsidiaryAuthorization` change type and the `SubsidiaryAuthorizationId` from step 1, as shown in the following example. + +**Request Syntax** + + + POST /StartChangeSet HTTP/1.1 + Content-type: application/json + + { + "Catalog": "AWSMarketplace", + "ChangeSet": [ + { + "ChangeType": "CreateOfferUsingSubsidiaryAuthorization", + "ChangeName": "TestingSubsidiaryOfferCreation", + "Entity": { + "Type": "[email protected]" + }, + "DetailsDocument": { + "SubsidiaryAuthorizationId": "subauthz-1a2bexample34", + "Name": "Test Subsidiary Offer" + } + } + ] + } + +Provide information for the fields to add the `CreateOfferUsingSubsidiaryAuthorization` change type: + + * **Entity** (object) (required) – Your offer. + + * **Type** (string) (required) – The `Type` is always `[email protected]`. + + * **DetailsDocument** (object) (required) – Specifics of the request. + + * **SubsidiaryAuthorizationId** (string) (required) – The entity ID of the subsidiary authorization that grants you permission to sell the product. Must match the pattern `subauthz-` followed by 13 alphanumeric characters, for example `subauthz-1a2bexample34`. + + * **Name** (string) (optional) – The display name of the offer. Up to 150 characters. + + * **OfferSetId** (string) (optional) – The offer set to associate the offer with. Must match the pattern `offerset-` followed by 13 alphanumeric characters, for example `offerset-b3f9EXAMPLE27`. The offer set must be owned by your account. + + + + +You don't supply the product ID or the seller of record. AWS Marketplace derives the product from the subsidiary authorization and sets the seller of record to your account. + +###### Note + +`Description` isn't collected on this change type, which matches the `CreateOffer` change type. + +**Response Syntax** + +A change set is created for your request. The response gives you the `ChangeSetId` and `ChangeSetArn` for the change set and looks like the following. + + + { + "ChangeSetId": "example444455556666abcdef", + "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:444455556666:AWSMarketplace/ChangeSet/example444455556666abcdef" + } + +The change request is added to a queue and processed. You can check the status of the request through the AWS Marketplace Management Portal, or directly through the Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation. If the `Status` is `SUCCEEDED`, a new `OfferId` is generated and the offer is in `Draft` state. + +###### Note + +AWS Marketplace re-validates the offer against the subsidiary authorization when you publish it with `ReleaseOffer`. If the primary account revoked or narrowed the authorization after you created the offer, the release fails. For more information, see Publish an offer. + +**Synchronous Validations** + +The following schema validations are specific to `CreateOfferUsingSubsidiaryAuthorization` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`. If the request doesn't meet the following requirements, it fails with an HTTP response. + +Input field | Validation rule | HTTP code +---|---|--- +SubsidiaryAuthorizationId | RequiredMust match `^subauthz-[a-zA-Z0-9]{13}$` | 422 +Name | OptionalUp to 150 charactersCan't begin with whitespace | 422 +OfferSetId | OptionalMust match `^offerset-[a-zA-Z0-9]{13}$`Must be owned by the calling account | 422 + +If your account isn't permitted to use the referenced subsidiary authorization, the request is denied with `AccessDeniedException`. Other failures are returned asynchronously through `DescribeChangeSet`, with `Status` set to `FAILED`, `FailureCode` set to `CLIENT_ERROR`, and a reason code in `ErrorDetailList`. + @@ -193 +333 @@ If your request has been processed successfully, AWS Marketplace Catalog API wil -To create a replacement offer, call the `StartChangeSet` API operation with the `CreateReplacementOffer` change type and provide a pre-existing agreement id, as shown in the following example. +To create a replacement offer for an agreement on a product that your own account owns, call the `StartChangeSet` API operation with the `CreateReplacementOffer` change type and provide a pre-existing agreement ID, as shown in the following example. To create a replacement offer for an agreement on an offer that you created from a subsidiary authorization, see Create a replacement offer using a subsidiary authorization. @@ -264,0 +405,103 @@ INCOMPATIBLE_AGREEMENT | **`CreateReplacementOffer change type can't be invoked +### Create a replacement offer using a subsidiary authorization + +You can use the Catalog API to issue refreshed terms to a buyer who has already accepted an offer you created from a subsidiary authorization, for example at renewal. + +The replacement offer is a new offer created against the buyer's existing purchase agreement. The prior offer isn't dropped, replaced, or modified. Both offers exist at the same time, and the buyer chooses which one to act on. + +**Step 1: Get your subsidiary authorization ID and agreement ID** + +You need two IDs: + + * **SubsidiaryAuthorizationId** – The ID of the `Active` subsidiary authorization that you created the prior offer under. To find it, call `ListEntities` as described in step 1 of Create an offer using a subsidiary authorization. + + * **AgreementId** – The ID of the buyer's existing agreement for the prior offer. + + + + +**Step 2: Create the replacement offer** + +To create a replacement offer using a subsidiary authorization, call the `StartChangeSet` API operation with the `CreateReplacementOfferUsingSubsidiaryAuthorization` change type, as shown in the following example. + +**Request Syntax** + + + POST /StartChangeSet HTTP/1.1 + Content-type: application/json + + { + "Catalog": "AWSMarketplace", + "ChangeSet": [ + { + "ChangeType": "CreateReplacementOfferUsingSubsidiaryAuthorization", + "ChangeName": "TestingSubsidiaryReplacementOfferCreation", + "Entity": { + "Type": "[email protected]" + }, + "DetailsDocument": { + "SubsidiaryAuthorizationId": "subauthz-1a2bexample34", + "AgreementId": "agmt-pqrs4567pqrs4567pqrs4567", + "Name": "Test Subsidiary Replacement Offer" + } + } + ] + } + +Provide information for the fields to add the `CreateReplacementOfferUsingSubsidiaryAuthorization` change type: +