AWS marketplace: Resale Authorization docs: reseller terminology, ResellerRole, validation updates
Summary
Large documentation refresh for AWS Marketplace Resale Authorizations: replaces 'channel partner' with 'reseller' throughout, adds the new ResellerRole field (ChannelPartner/Distributor) and Brazil 2P authorizations, moves the Update Resale Authorization details section, and updates many synchronous/asynchronous validation rules, error codes, currency lists, and pricing limits.
Security assessment
The diff is a terminology/API-reference update (channel partner -> reseller), a new ResellerRole input field, a new Brazil 2P topic link, and revised input validation rules/error messages for the Catalog API. It documents API usage and validation constraints but does not reference any vulnerability, CVE, incident, or security control change, so it is not security-issue related.
Evidence
+ * **ResellerRole** (string) (required) – The role of the targeted reseller. Valid values are `ChannelPartner` and `Distributor`. If you don't specify a value, `ChannelPartner` is used.
Diff
diff --git a/marketplace/latest/developerguide/work-with-resale-authorizations.md b/marketplace/latest/developerguide/work-with-resale-authorizations.md index 787f07d..fdb4c17 100644 --- a//marketplace/latest/developerguide/work-with-resale-authorizations.md +++ b//marketplace/latest/developerguide/work-with-resale-authorizations.md @@ -7 +7 @@ -Resale Authorization prerequisitesCreate a new Resale AuthorizationUpdate buyer targetingUpdate availabilityUpdate the validity of a future dated agreementUpdate legal resourcesUpdate pricingUpdate payment scheduleUpdate net payment termsUpdate Resale Authorization detailsRestrict a Resale AuthorizationRelease a Resale Authorization and make it visible to a Channel PartnerDescribe an existing Resale Authorization +Resale Authorization prerequisitesCreate a new Resale AuthorizationUpdate Resale Authorization detailsUpdate buyer targetingUpdate availabilityUpdate the validity of a future dated agreementUpdate legal resourcesUpdate pricingUpdate payment scheduleUpdate net payment termsRestrict a Resale AuthorizationRelease a Resale AuthorizationDescribe an existing Resale Authorization @@ -17 +17 @@ While the _product_ describes what is being sold in AWS Marketplace, the _Resale -A Resale Authorization has a collection of terms and rules to be accepted for a reseller agreement between manufacturers and channel partners. Accepting the terms of the Resale Authorization allows the reseller to create offers for the product per the conditions expressed in the terms. +A Resale Authorization has a collection of terms and rules to be accepted for a reseller agreement between manufacturers and resellers. Accepting the terms of the Resale Authorization allows the reseller to create offers for the product per the conditions expressed in the terms. @@ -23 +23 @@ There are two types of rules in a Resale Authorization: - * **PartnerTargetingRule** – Specifies whether the Resale Authorization should be accessible to a specific set of channel partners. + * **PartnerTargetingRule** – Specifies the single reseller that the Resale Authorization is accessible to, and that reseller's role. @@ -32 +32 @@ See the following resources: - * For code examples of API requests, see [Python](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/python/src/catalog_api/resale_authorization) and [Java](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/java/resources/changeSets/channel_partner_offers) examples in _AWS Samples_ on GitHub. + * For code examples of API requests, see [Python](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/python/src/catalog_api/resale_authorization) and [Java](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/java/resources/changeSets/resaleAuthorization) examples in _AWS Samples_ on GitHub. @@ -44,0 +45,2 @@ The following topics describe how to use the Catalog API to create and update Re + * [Brazil 2P Authorizations](./brazil-2p-authorizations.html) + @@ -46,0 +49,2 @@ The following topics describe how to use the Catalog API to create and update Re + * Update Resale Authorization details + @@ -61,2 +64,0 @@ The following topics describe how to use the Catalog API to create and update Re - * Update Resale Authorization details - @@ -65 +67 @@ The following topics describe how to use the Catalog API to create and update Re - * Release a Resale Authorization and make it visible to a Channel Partner + * Release a Resale Authorization @@ -74 +76 @@ The following topics describe how to use the Catalog API to create and update Re -To use Resale Authorization, both independent software vendors (ISVs) and AWS Marketplace Channel Partners must create a service-linked role that provides resource-sharing permissions to AWS. If both groups don't perform this prerequisite, AWS can't share the authorization resource from the ISV to the AWS Marketplace Channel Partner. For more information, see [Using roles for Resale Authorization for AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/userguide/using-roles-for-resale-authorization.html) in the _AWS Marketplace Seller Guide_. +To use Resale Authorization, both independent software vendors (ISVs) and AWS Marketplace resellers must create a service-linked role that provides resource-sharing permissions to AWS. If both groups don't perform this prerequisite, AWS can't share the authorization resource from the ISV to the reseller. For more information, see [Using roles for Resale Authorization for AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/userguide/using-roles-for-resale-authorization.html) in the _AWS Marketplace Seller Guide_. @@ -80 +82 @@ You can use the Catalog API to create a new Resale Authorization in AWS Marketpl -If your request is processed successfully, AWS Marketplace Catalog API generates a Resale Authorization in `Draft` state for you. It's an incomplete Resale Authorization and not visible to channel partners in AWS Marketplace. +If your request is processed successfully, AWS Marketplace Catalog API generates a Resale Authorization in `Draft` state for you. It's an incomplete Resale Authorization and not visible to resellers in AWS Marketplace. @@ -82 +84 @@ If your request is processed successfully, AWS Marketplace Catalog API generates -Use the `Update` change types to complete the Resale Authorization. After the Resale Authorization is completed, use the `ReleaseResaleAuthorization` change type to complete the Resale Authorization creation process and release the Resale Authorization, which will validate the entire Resale Authorization and make your it visible to channel partners in AWS Marketplace. +Use the `Update` change types to complete the Resale Authorization. After the Resale Authorization is completed, use the `ReleaseResaleAuthorization` change type to complete the Resale Authorization creation process and release the Resale Authorization, which will validate the entire Resale Authorization and make it visible to resellers in AWS Marketplace. @@ -108 +110,2 @@ To create a Resale Authorization in `Draft` state, call the `StartChangeSet` API - "ResellerAccountId": "777788889999" + "ResellerAccountId": "777788889999", + "ResellerRole": "ChannelPartner" @@ -125 +128 @@ Provide information for the input fields to add the `CreateResaleAuthorization` - * **Name** (string) (required) – Name associated with the ResaleAuthorization for better readability to you and your channel partners. + * **Name** (string) (required) – Name associated with the ResaleAuthorization for better readability to you and your resellers. @@ -129 +132,5 @@ Provide information for the input fields to add the `CreateResaleAuthorization` - * **ResellerAccountId** (string) (required) – Add targeted channel partner's AWS account who can describe and use this `ResaleAuthorization` to create a private offer. + * **ResellerAccountId** (string) (required) – Add targeted reseller's AWS account who can describe and use this `ResaleAuthorization` to create a private offer. + + * **ResellerRole** (string) (required) – The role of the targeted reseller. Valid values are `ChannelPartner` and `Distributor`. If you don't specify a value, `ChannelPartner` is used. + +**The`Distributor` value is currently available only for Brazil 2P.** For more information, see [Brazil 2P Authorizations](./brazil-2p-authorizations.html). @@ -174,2 +181 @@ The following shows the response from the [DescribeChangeSet](https://docs.aws.a - "ResellerAccountId": "777788889999", - "BulkRequestId": "84977023-5093-4a66-8b24-ef2c5a2f8b1f" + "ResellerAccountId": "777788889999" @@ -195 +201 @@ ResellerAccountId | Required Must not be empty AWS account IDs must be in valid -BulkRequestId | Optional Length must be between 1 and 50 characters Must be in UUID format | 422 +ResellerRole | Required Must be either `ChannelPartner` or `Distributor` Defaults to `ChannelPartner` if omitted | 422 @@ -204,0 +211,103 @@ INVALID_RESELLER_ACCOUNT | **`Provide a valid reseller account.`** +INCOMPATIBLE_PRODUCT | **`Managing ResaleAuthorizations for the product isn't currently supported in the AWS Marketplace Catalog API.`** + +## Update Resale Authorization details + +You can use the Catalog API to update Resale Authorization details in AWS Marketplace. + +To update Resale Authorization details, call the `StartChangeSet` API operation with the `UpdateInformation` change type, as shown in the following example. + +###### Note + +The `UpdateInformation` change type only updates the sections provided in the request; all other information remains unchanged. + +**Request Syntax** + + + POST /StartChangeSet HTTP/1.1 + Content-type: application/json + + { + "Catalog": "AWSMarketplace", + "ChangeSet": + [ + { + "ChangeType": "UpdateInformation", + "Entity": + { + "Type": "[email protected]", + "Identifier": "resaleauthz-123456789" + }, + "DetailsDocument": + { + "Name": "TestResaleAuthorization", + "Description": "Worldwide ResaleAuthorization for Test Product", + "PreExistingBuyerAgreement": + { + "AcquisitionChannel": "AwsMarketplace", + "PricingModel": "Contract" + } + } + } + ] + } + +Provide information for the fields to add the `UpdateInformation` change type: + + * **Entity** (object) (required) – Your Resale Authorization. + + * **Type** (string) (required) – The `Type` is always `[email protected]`. + + * **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](./catalog-apis.html#identifier). + + * **DetailsDocument** (object) (required) – Details of the request, including the information you want to update information for the Resale Authorization. + + * **Name** (string) (optional) – The name associated with the ResaleAuthorization for better readability to you and your resellers. + + * **Description** (string) (optional) – The description is free-form text where you can add details about the ResaleAuthorization. + + * **PreExistingBuyerAgreement** (object) (optional) – Determines if this offer is a renewal for an existing agreement with an existing customer for the same underlying product. 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. + + * **AcquisitionChannel** (string) (required) – Indicates if the existing buyer agreement was signed outside AWS Marketplace or in AWS Marketplace. + +Possible values: `External`, `AwsMarketplace` + + * **PricingModel** (string) (required) **–** Indicates which pricing model the exiting agreement uses. + +Possible values: `Contract`, `Usage`, `BYOL`, `Free` + + + + +**Response Syntax** + +A change set is created for your request. The response to this request gives you the `ChangeSetId` and `ChangeSetArn` for the change set and looks like the following. + + + { + "ChangeSetId": "example123456789012abcdef", + "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef" + } + +The change request is added to a queue and processed. This includes validating information to ensure that it meets the AWS Marketplace guidelines. The validation process can take anywhere from a few minutes to a few hours. + +You can check the status of the request through the AWS Marketplace Management Portal, or directly through Catalog API using the `[DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html)` API operation. + +**Synchronous Validations** + +The following schema validations are specific to `UpdateInformation` actions in the AWS Marketplace Catalog API. These validations are performed when you call `StartChangeSet`, and the request will fail with an HTTP error if the input does not meet the following requirements. + +Input field | Validation rule | HTTP code +---|---|--- +Name | Optional Must not be null or empty Length must be between 1 and 100 characters Must not begin with a white space character Must not end with a backslash | 422 +Description | Optional Can be set to `null` to remove the existing description Length must be between 1 and 255 characters Must not begin with a white space character Must not end with a backslash | 422 +PreExistingBuyerAgreement | Optional Can be set to `null` to remove the existing agreement When provided, both `AcquisitionChannel` and `PricingModel` are required `AcquisitionChannel` allowed values: `AwsMarketplace`, `External` `PricingModel` allowed values: `Byol`, `Free`, `Usage`, `Contract` | 422 +DetailsDocument | Must include at least one of `Name`, `Description`, or `PreExistingBuyerAgreement` | 422 +An unknown property | No additional properties are allowed | 422 + +**Asynchronous Errors** + +The following errors are specific to `UpdateInformation` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. or more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](./catalog-apis.html#working-with-change-sets). + +Error code | Error message +---|--- +INCOMPATIBLE_BUYER_TARGETING | **`At least one Buyer account must be present for ResaleAuthorization with PreExistingBuyerAgreement.`** @@ -259 +368 @@ Provide information for the fields to add the `UpdateBuyerTargetingTerms` change - * **Terms** (array of structures) (optional) – List of buyers targeting terms that you want to update. If the intentions aren't to target the `ResaleAuthorization` to any specific buyer, then terms field can be skipped. By default, `ResaleAuthorization` is targeted to all buyers. Supported terms are: + * **Terms** (array of structures) (required) – List of buyers targeting terms that you want to update. If the intentions aren't to target the `ResaleAuthorization` to any specific buyer, then pass an empty list. By default, `ResaleAuthorization` is targeted to all buyers. Supported terms are: @@ -267 +376 @@ Provide information for the fields to add the `UpdateBuyerTargetingTerms` change - * **BuyerAccounts** (array of strings) (optional) – List as optional. You can add the targeted buyer's AWS accounts. If the intention isn't to target `ResaleAuthorization` to specific buyers, then this field should be omitted. By default, all buyers are targeted. Targeted channel partners can choose to create a private offer and target a subset of buyers, if specified. + * **BuyerAccounts** (array of strings) (optional) – List as optional. You can add the targeted buyer's AWS accounts. If the intention isn't to target `ResaleAuthorization` to specific buyers, then this field should be omitted. By default, all buyers are targeted. Targeted resellers can choose to create a private offer and target a subset of buyers, if specified. @@ -292 +401 @@ Input field | Validation rule -Terms | Optional Must not be null or empty Only "BuyerTargetingTerm" is allowed in the list List size must be 1 (there is no use case today that requires multiple buyer terms) +Terms | Required Only "BuyerTargetingTerm" is allowed in the list List size must be at most 1 (there is no use case today that requires multiple buyer terms) Pass an empty list to remove buyer targeting @@ -349 +458 @@ Provide information for the fields to add the `UpdateAvailability` change type: - * **AvailabilityEndDate** (string) (optional) – Define the end date until Channel Partners can leverage the `ResaleAuthorization` to create an offer. Channel Partners can use this `ResaleAuthorization` multiple times until the specified end date. Dates are represented in ISO_8601 format. + * **AvailabilityEndDate** (string) (optional) – Define the end date until resellers can leverage the `ResaleAuthorization` to create an offer. Resellers can use this `ResaleAuthorization` multiple times until the specified end date. Dates are represented in ISO_8601 format. @@ -377 +486 @@ OffersMaxQuantity | Optional Must be non-negative integer Allowed value only "1 -AvailabilityEndDate | Optional Must be ISO_8601 formatted Must be date in the future +AvailabilityEndDate | Optional Must be ISO_8601 formatted Must be date in the future Must be within 10 years from the current date @@ -474 +583 @@ Input field | Validation rule -Terms | Required Must not be null or empty Only "BuyerValidityTerm" is allowed in the list List size must be 1 (there's no use case today that requires multiple service availability terms) +Terms | Required Only "BuyerValidityTerm" is allowed in the list List size must be at most 1 (there's no use case today that requires multiple service availability terms) Pass an empty list to remove the agreement validity term @@ -491 +600 @@ You can use the Catalog API to replace the existing legal terms completely in AW -The legal terms that aren't included in the latest request will be removed from the Resale Authorization. `BuyerLegalTerm` contains the EULA which will be included on the final buyer agreement and `LegalTerm` includes the Reseller Contract which will be included in the reseller agreement between the channel partner and the ISV. +The legal terms that aren't included in the latest request will be removed from the Resale Authorization. `BuyerLegalTerm` contains the EULA which will be included on the final buyer agreement and `LegalTerm` includes the Reseller Contract which will be included in the reseller agreement between the reseller and the ISV. @@ -553 +662 @@ Provide information for the fields to add the `UpdateLegalTerms` change type: - * **Terms** (array of structures) (required) – List of legal terms. Supported legal terms are: + * **Terms** (array of structures) (required) – List of legal terms. Each entry must be one of the following term types, and each term type can be present only one time. To remove all legal terms, pass an empty list. Supported legal terms are: @@ -555 +664 @@ Provide information for the fields to add the `UpdateLegalTerms` change type: - * **BuyerLegalTerm** (object) (required) – Defines the list of text agreements to be proposed to acceptors. For example, the end user license agreement (EULA). + * **BuyerLegalTerm** (object) (optional) – Defines the list of text agreements to be proposed to acceptors. For example, the end user license agreement (EULA). @@ -571 +680 @@ Provide information for the fields to add the `UpdateLegalTerms` change type: - * **ResaleLegalTerm** (object) (optional) – Defines the list of text agreements to propose only to channel partners. This term won't be available to buyers. + * **ResaleLegalTerm** (object) (optional) – Defines the list of text agreements to propose only to resellers. This term won't be available to buyers. @@ -575 +684 @@ Provide information for the fields to add the `UpdateLegalTerms` change type: - * **Documents** (array of structures) (required) – List of references to the reseller legal resources to be proposed to the channel partners. + * **Documents** (array of structures) (required) – List of references to the reseller legal resources to be proposed to the resellers. @@ -579 +688 @@ Provide information for the fields to add the `UpdateLegalTerms` change type: - * **StandardResellerContract** – Standard Reseller Contract for AWS Marketplace. + * **StandardResellerContract** – [Standard Reseller Contract for AWS Marketplace](https://s3.amazonaws.com/aws-mp-rcmp/Reseller-Contract-for-AWS-Marketplace-2021-12-01.pdf). You don't need to provide a URL for this type because it's managed by AWS Marketplace. @@ -583 +692 @@ Provide information for the fields to add the `UpdateLegalTerms` change type: - * **Url** (string) (conditionally required) – URL to the reseller contract document for channel partners to read. It's required when the Type is CustomResellerContract.