# Work with offers using the AWS Marketplace APIs
An offer defines the terms and rules governing the purchase and consumption of a product. It encompasses a collection of agreement terms between two parties. The accepted offer terms are then translated into an agreement, serving as proof of the transaction.
The following sections provide information on how to manage offers as a seller or channel partner.
**Topics**
+ [
# Work with private offers using the AWS Marketplace APIs
](work-with-private-offers.md)
+ [
# Work with resale authorizations using the AWS Marketplace APIs
](work-with-resale-authorizations.md)
+ [
# Work with channel partner private offers using the AWS Marketplace APIs
](work-with-cppos.md)
+ [
# Work with renewals
](work-with-renewals.md)
# Work with private offers using the AWS Marketplace APIs
You can use the AWS Marketplace Catalog API to automate tasks for working with offers.
While the *product* describes what is being sold in AWS Marketplace, the *offer* describes the terms and rules of how a product is purchased and consumed. AWS Marketplace products can have multiple offers sold by different sellers. Each AWS Marketplace offer, however, can only be created for one product. An *offer* contains a collection of agreement terms between two parties. The accepted offer terms are translated into an agreement as proof of a transaction.
There are two types of offers:
+ **Private offers** are for sellers and buyers to negotiate pricing. Sellers sign an end-user license agreement (EULA) for software purchases in AWS Marketplace. An offer is visible only to a specified buyer. For more information, see [Private offers](https://docs.aws.amazon.com/marketplace/latest/userguide/private-offers-overview.html) in the *AWS Marketplace Seller Guide*.
+ **Public offers** are for global purchasing programs. Sellers identify customers based on available programs and geographical locations, which makes the offer accessible only to specific customers.
See the following resources:
+ For working code examples, see [Manage offers with API](https://catalog.workshops.aws/mpseller/en-US/manage-offers-with-api) in the *AWS Marketplace seller workshop*.
+ For API request code examples, see [Python](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/python/src/catalog_api/offers) and [Java](https://github.com/aws-samples/aws-marketplace-reference-code/tree/main/java/resources/changeSets/offers) examples in *AWS Samples* on GitHub.
+ For a video on creating private offers, see [Create a Private Offer Using the AWS Marketplace Catalog API](https://www.youtube.com/watch?v=Gg9JR0tB330) on YouTube.
+ For a video on updating AMI pricing, see [Update AMI Product Pricing Using the AWS Marketplace Catalog API](https://www.youtube.com/watch?v=AVIRlzHKEJw) on YouTube.
The following topics describe how to use the Catalog API to create and update offers:
**Topics**
+ [
## Create an offer
](#create-offer)
+ [
## Create a replacement offer
](#create-replacement-offer)
+ [
## Update offer information
](#update-offer-information)
+ [
## Update targeting configuration
](#update-targeting-offers)
+ [
## Update refund policy
](#update-support-terms)
+ [
## Update legal resources
](#update-legal-terms)
+ [
## Update pricing
](#update-pricing-terms)
+ [
## Update the discoverability of the offer
](#update-availability)
+ [
## Define the expiration date of agreements created using the offer
](#update-validity-terms)
+ [
## Update payment schedule details
](#update-payment-schedule-terms)
+ [
## Modify renewal options
](#update-renewal-terms)
+ [
## Publish an offer
](#release-offer)
+ [
## Describe existing offer details
](#describe-entity)
## Create an offer
You can use the Catalog API to create a new offer in AWS Marketplace. If your request processes successfully, the AWS Marketplace Catalog API creates a `Draft`, which is an incomplete offer that's invisible to buyers. To complete an offer, use the `Update` change type. When the offer is complete, use the [`ReleaseOffer`](#release-offer) change type to create and release it. Releasing an offer validates it and makes it visible to buyers in AWS Marketplace.
To create a new offer, call the `StartChangeSet` API operation with the `CreateOffer` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "CreateOffer",
"Entity": {
"Type": "Offer@1.0"
},
"DetailsDocument": {
"ProductId": "prod-ad8EXAMPLE51",
"Name": "Test Offer",
"OfferSetId": "offerset-b3f9EXAMPLE27"
}
}
]
}
```
Provide information for the fields to add the `CreateOffer` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **ProductId** (string) (required) – The unique identifier of the product being offered.
+ **Name** (string) (optional) – The name associated with the offer for better readability to you and your customers. It is displayed as a part of the Agreement information as well.
+ **OfferSetId** (string) (optional) – The ID of the offer set to associate this offer with. Only specify this field when creating an offer that will be part of an offer set. If OfferSetId is not provided, an individual offer will be created that can be purchased standalone. Note that specifying an OfferSetId during offer creation only indicates your intent to associate the offer with that offer set. To complete the association, you must [use the AssociateOffers change type](work-with-offer-sets.md#associate-offers) after the offer is created.
**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.
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.
If the `Status` is `SUCCEEDED`, then a new `OfferId` is generated.
The response looks like the following.
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef",
"ChangeSetName": "Submitted by 123456789012",
"StartTime": "2021-05-27T22:21:26Z",
"EndTime": "2021-05-27T22:32:19Z",
"Status": "SUCCEEDED",
"ChangeSet": [
{
"ChangeType": "CreateOffer",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"ProductId": "prod-ad8EXAMPLE51",
"Name": "Test Offer"
},
"ErrorDetailList": []
}
]
}
```
**Synchronous Validations**
The following schema validations are specific to `CreateOffer` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| ProductId | Required Length must be between 1 and 50 characters Must not contain illegal characters (\$1, <, >) | 422 |
| ProductId | RequiredUser must be authorized to create offer for the given product | 403 |
| ProductId | RequiredMust be an existing product in the catalog or being created in the same change set | 404 |
| Name | Optional Length must be between 1 and 150 characters Must not contain illegal characters (\$1, <, >) | 422 |
**Asynchronous Errors**
The following errors are specific to `CreateOffer` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT | Use an active product in Limited or Public state. |
| INCOMPATIBLE\$1PRODUCT | Managing offers for your chosen product type isn't currently supported in the AWS Marketplace Catalog API. |
| INCOMPATIBLE\$1PRODUCT | Managing offers for the product isn't currently supported in the AWS Marketplace Catalog API. |
| INCOMPATIBLE\$1PRODUCT | OfferSetId isn't supported in offers for the product. |
| INCOMPATIBLE\$1PRODUCT | CreateOffer change type can't be invoked to create an offer for the product. Use CreateOfferUsingResaleAuthorization change type. |
## Create a replacement offer
You can use the Catalog API to create a replacement offer (also known as an agreement-based offer) in AWS Marketplace.
If your request has been processed successfully, AWS Marketplace Catalog API will have an offer in `Draft` state generated for you, which is an incomplete offer and not visible to buyers on AWS Marketplace. You will use `Update` change types to complete the offer. After the offer is completed, you will use [`ReleaseOffer`](#release-offer) change type to complete offer creation process and release the offer, which will validate the entire offer and make your offer visible to buyers on AWS Marketplace. From there, the buyer has the option to accept the replacement offer or to continue to operate under the original agreement.
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.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "CreateReplacementOffer",
"Entity": {
"Type": "Offer@1.0"
},
"DetailsDocument": {
"AgreementId": "agmt-12345",
"Name": "Offer name"
}
}
]
}
```
Provide information for the fields to add the `CreateReplacementOffer` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **AgreementId** (string) (required) – The unique identifier for the current agreement to be replaced.
+ **Name** (string) (optional) – The name associated with the offer for better readability to you and your customers. It will be displayed as part of Agreement information as well.
**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.
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 `CreateReplacementOffer` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP Code |
| --- | --- | --- |
| AgreementId | RequiredLength must be between 1 and 64 characters | 422 |
| AgreementId | RequiredUser must be authorized to create offer for the given agreement | 403 |
| Name | OptionalLength must be between 1 and 150 charactersMust not contain invalid characters (\$1, <, >) | 422 |
**Asynchronous Errors**
The following errors are specific to `CreateReplacementOffer` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT | Replacement offers aren't supported for the product. |
| INCOMPATIBLE\$1AGREEMENT | CreateReplacementOffer change type can't be invoked to create a replacement offer for the agreement. Use CreateReplacementOfferUsingResaleAuthorization change type. |
## Update offer information
You can use the Catalog API to update the offer information in AWS Marketplace.
To update the offer information, call the `StartChangeSet` API operation with the `UpdateInformation` change type, as shown in the following example. All other information will remain unchanged.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateInformation",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Name": "New offer name",
"Description": "New offer description",
"PreExistingAgreement": {
"AcquisitionChannel": "External",
"PricingModel": "Contract"
}
}
}
]
}
```
Provide information for the fields to add the `UpdateInformation` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Name** (string) (optional) – Name associated with the offer for better readability. It is displayed as part of agreement information.
+ **Description** (string) (optional) – A free-form text that is meant to be used only by you and will never be visible to buyers.
+ **PreExistingAgreement** (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 agreement was signed outside AWS Marketplace or within AWS Marketplace.
Possible values: `External`, `AwsMarketplace`
+ **PricingModel** (string) (required) – Indicates which pricing model the existing 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 a few minutes.
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`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Properties | At least one of the following properties must be provided | 422 |
| Name | Optional Length must be between 1 and 150 characters Must not contain illegal characters (\$1, <, >) | 422 |
| Description | Optional Length must be between 1 and 255 characters | 422 |
| PreExistingAgreement | OptionalCan be null to remove `PreExistingAgreement` from offer | 422 |
| PreExistingAgreement.PricingModel | Required Can be one of these values: [`Byol`, `Free`, `Usage`, `Contract`] | 422 |
| PreExistingAgreement.AcquisitionChannel | Required Can be one of these values: [`AwsMarketplace`, `External`] | 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. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRE\$1EXISTING\$1AGREEMENT | PreExistingAgreement can't be changed after the offer is released. |
## Update targeting configuration
You can use the Catalog API to update the targeting configuration of your offer in AWS Marketplace.
All existing targeting options that aren't included in the latest request and will be removed from the offer.
**Note**
An offer can optionally include `PositiveTargeting` or `NegativeTargeting`, but not both.
**Positive Targeting options:**
**Country codes only** – Creates a public offer available to buyers in the specified countries.
**Buyer accounts only** – Creates a private offer targeted to specific AWS accounts.
**Both country codes and buyer accounts** – Creates a private offer where targeted accounts can only accept the offer if they are located in one of the specified countries.
**Negative Targeting options:**
**Country codes** – Excludes buyers from the specified countries. This creates a public offer available to all countries except those listed.
To update the targeting configuration of your offer, call the `StartChangeSet` API operation with the `UpdateTargeting` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateTargeting",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"PositiveTargeting": {
"CountryCodes": [
"US",
"CA"
],
"BuyerAccounts": [
"111122223333"
]
},
"NegativeTargeting": {
"CountryCodes": [
"XX"
]
}
}
}
]
}
```
Provide information for the fields to add the `UpdateTargeting` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **PositiveTargeting** (object) (optional) – Positive targeting defines the criteria which any buyer's profile should fulfill in order to be allowed to access the offer. This field is optional, but at least one targeting option should be provided when this field is present.
+ **CountryCodes** (array of strings) (optional) – List as option for allowing targeting based on country. If the intention isn’t to target the offer to a country, this field should be omitted. If it’s present, the list must contain at least one country code. Each element in this list should be a valid 2-letter country code, using this format: ISO 3166-1 alpha-2.
+ **BuyerAccounts** (array of strings) (optional) – List as an option to allow targeting based on AWS accounts (also known as Private Offer). If the intention is to not target the offer to an AWS account, this field should be omitted.
+ **NegativeTargeting** (object) (optional) – Negative targeting defines the criteria which any customer's profile should fulfill to be restricted to access the offer. Although this field is optional, at least one targeting option should be provided when this field is present.
+ **CountryCodes** (array of strings) (required) – List as option for allowing targeting based on country. If the intention isn’t to target the offer to a specific country, then this field should be omitted. If it’s present, the list must contain at least one country code. Each element in this list should be a valid 2-letter country code using this format: ISO 3166-1 alpha-2.
**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 a few minutes.
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 `UpdateTargeting` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| NegativeTargeting | Optional Can have either one of the following: [`CountryCodes`] | 422 |
| NegativeTargeting.CountryCodes | Optional List size must be between 1 and 244 Country codes must be valid (ISO 3166-1 alpha-2) | 422 |
| PositiveTargeting | Optional Can have either one of the following: [`CountryCodes`, `BuyerAccounts`] | 422 |
| PositiveTargeting.BuyerAccounts | Optional List size must be between 1 and 26 AWS account IDs must be in valid format (12-digit number) | 422 |
| PositiveTargeting.CountryCodes | Optional List size must be between 1 and 244 Country codes must be valid (ISO 3166-1 alpha-2) | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateTargeting` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1BUYER\$1ACCOUNTS | Provide valid buyer accounts. Invalid accounts: [x]. |
| INVALID\$1COUNTRY\$1CODES | Provide supported country codes. |
| INVALID\$1TARGETING | Use either negative or positive targeting on the same attribute. |
| INCOMPATIBLE\$1PRODUCT | Country-based targeting isn't supported for the product. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide BuyerAccounts that are compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1TARGETING | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TARGETING | The requested change can't be performed after the offer is expired. |
| INCOMPATIBLE\$1TARGETING | Targeting can't be updated on a replacement offer. If the buyer isn't associated with the provided AgreementId, then create a new private offer by providing an AgreementId associated with the buyer. |
| TOO\$1MANY\$1BUYER\$1ACCOUNTS | Provide BuyerAccounts within the allowed limits. |
| INCOMPATIBLE\$1TARGETING | BuyerAccounts can't be removed after the offer is released. |
| INCOMPATIBLE\$1TARGETING | BuyerAccounts can't be added after the offer is released. |
| MISSING\$1COUNTRY\$1CODES | Provide PositiveTargeting with CountryCodes: [x]. |
| INCOMPATIBLE\$1COUNTRY\$1CODES | Provide CountryCodes that are compatible. |
| INCOMPATIBLE\$1BUYER\$1ACCOUNTS | Provide BuyerAccounts that are compatible with the agreement. |
## Update refund policy
You can use the Catalog API to update the refund policy of your offer in AWS Marketplace.
This change doesn’t affect existing agreements. The support terms that aren't included in the latest request will be removed from the offer.
To update the refund policy, call the `StartChangeSet` API operation with the `UpdateSupportTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateSupportTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "SupportTerm",
"RefundPolicy": "Updated refund policy description"
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateSupportTerms` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Terms** (array of structures) (required) – List of support terms that you would like to update. Accepted support terms are:
+ **SupportTerm** (object) (required) – Defines the customer support available for the acceptors when they purchase the software.
+ **Type** (string) (required) – Type of the term being updated. This is the object value: `"SupportTerm"`.
+ **RefundPolicy** (string) (required) – Free-text field about the refund policy description that will be shown to customers as is on the website and console.
**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 a few minutes.
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 `UpdateSupportTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Terms | Required | 422 |
| Terms[].RefundPolicy | Required Length must be between 1 and 500 Cannot lead or end with spaces | 422 |
| Terms[].Type | RequiredCan only be `SupportTerm` | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateSupportTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT | SupportTerm isn't supported in private offers for the product. |
| INCOMPATIBLE\$1TERMS | SupportTerm isn't supported for free trial offers. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
## Update legal resources
You can use the Catalog API to replace the existing legal documents, such as an end user license agreement (EULA). The legal terms that aren't included in the latest request will be removed from the offer.
To update legal resources of your offer, call the `StartChangeSet` API operation with the `UpdateLegalTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateLegalTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "LegalTerm",
"Documents": [
{
"Type": "CustomEula",
"Url": "https://s3.amazonaws.com/EULA/custom-eula-1234.txt"
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateLegalTerms` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **LegalTerm** (object) (required) – Defines the list of text agreements to be proposed to the acceptors. One example of such an agreement is the end user license agreement (EULA).
+ **Type** (string) (required) – Type of the term being updated. This is the object value: `"LegalTerm"`.
+ **Documents** (array of structures) (required) – List of references to legal resources to be proposed to the buyers. One example of such a resource is the end user license agreement (EULA). Each reference is made up of a `Type` and a `URL`:
+ **Type** (string) (required) – Type of document. Available document types are:
+ **CustomEula** – A custom EULA provided by you as seller. Either a public S3 URL or a [presigned URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html) is required for this document type.
+ **StandardEula** – Standard Contract For AWS Marketplace (SCMP). For more information about SCMP, see the AWS Marketplace Seller Guide. You don’t provide a URL for this type because it is managed by AWS Marketplace.
+ **Url** (string) (conditionally required) – A URL to the legal document for buyers to read. Required when `Type` is one of the following [`CustomEula`].
+ **Version** (string) (conditionally required) – Version of standard contracts provided by AWS Marketplace. Required when `Type` is [`StandardEula`]. Available version:
+ **2022-07-14** – This version of the Standard Contract for AWS Marketplace is available from this Amazon S3 bucket: [https://s3.amazonaws.com/aws-mp-standard-contracts/Standard-Contact-for-AWS-Marketplace-2022-07-14.pdf](https://s3.amazonaws.com/aws-mp-standard-contracts/Standard-Contact-for-AWS-Marketplace-2022-07-14.pdf)
**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 a few minutes.
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 `UpdateLegalTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Terms | Required Only `LegalTerm` is allowed in the list List size must be 1 | 422 |
| Terms[].Type | RequiredCan only be `LegalTerm` | 422 |
| Terms[].LegalTerm.Documents | Required | 422 |
| Terms[].LegalTerm.Documents[].Type | Required Allowed values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-private-offers.html) | 422 |
| Terms[].LegalTerm.Documents[].Url | Required and must be a valid URL when Type is CustomEula | 422 |
| Terms[].LegalTerm.Documents[].Version | Required and must be a valid Version when Type is StandardEulaValid `StandardEula` versions: ["2019-04-24", "2022-07-14"] | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateLegalTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1LEGAL\$1DOCUMENTS | Provide URLs for legal documents stored in accessible S3 buckets. |
| INVALID\$1LEGAL\$1DOCUMENTS | Only the most recent version of StandardEula is supported for new offers. |
| INVALID\$1LEGAL\$1DOCUMENTS | Provide legal documents in the supported file formats. |
| INVALID\$1LEGAL\$1DOCUMENTS | Provide legal documents using the supported document types. |
| LIMIT\$1EXCEEDED\$1LEGAL\$1DOCUMENT\$1SIZE | Provide legal documents within the allowed size limits. |
| INVALID\$1LEGAL\$1DOCUMENTS | LegalTerm contains password-protected document(s). Provide accessible documents in LegalTerm. |
| INVALID\$1LEGAL\$1DOCUMENTS | LegalTerm contains invalid PDF document(s). Provide accessible documents in LegalTerm. |
## Update pricing
You can use the Catalog API to replace the existing pricing terms completely. The pricing terms that aren't included in the latest request will be removed from the offer.
To update pricing terms for your offer, call the `StartChangeSet` API operation with the `UpdatePricingTerms` change type, as shown in the following example.
**Note**
The following request syntax combines multiple examples. This combination doesn't work as a valid payload. For example, a `Terms` array can't include both the term type `FixedUpfrontPricingTerm` and the term type `ConfigurableUpfrontPricingTerm`. For examples of how different term types are combined for different pricing use cases, see [Manage offers with API](https://catalog.workshops.aws/mpseller/en-US/manage-offers-with-api) in the *AWS Marketplace seller workshop*.
**Note**
For SaaS products with Free pricing model, you must include either `UsageBasedPricingTerm` or `ConfigurableUpfrontPricingTerm` with at least one RateCard (dimension) where all prices are set to \$10.00. This requirement is unique to SaaS products.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"PricingModel": "Usage",
"Terms": [
{
"Type": "UsageBasedPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "0.10"
},
{
"DimensionKey": "m4.xlarge",
"Price": "0.20"
}
]
}
]
},
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P365D"
},
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "300"
},
{
"DimensionKey": "m4.xlarge",
"Price": "400"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
},
{
"Type": "ByolPricingTerm"
},
{
"Type": "RecurringPaymentTerm",
"CurrencyCode": "USD",
"BillingPeriod": "Monthly",
"Price": "100.0"
},
{
"Type": "FixedUpfrontPricingTerm",
"CurrencyCode": "USD",
"Price": "200.00",
"Grants": [
{
"DimensionKey": "Users",
"MaxQuantity": 10
}
]
},
{
"Type": "FreeTrialPricingTerm",
"Duration": "P30D",
"Grants": [
{
"DimensionKey": "m3.xlarge",
"MaxQuantity": 10
},
{
"DimensionKey": "m4.xlarge",
"MaxQuantity": 10
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdatePricingTerms` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **PricingModel** (string) (required) – Pricing model for your offer. Possible values for pricing model are:
+ **Usage** – Usage-based pricing model where buyers will be billed for their usage of your product.
+ **Contract** – Contract-based pricing model where buyers are either billed in advance for the use of your product, or offered a flexible payment schedule. Buyers can also pay for an additional usage above their contract.
+ **Free** – Free pricing model where buyers will not be charged for usage of product. When using this pricing model no pricing terms or payment schedule term can have non-zero rates.
+ **Byol** – Byol pricing model where buyers will bring their own license for usage of the product.
+ **Terms** (array of structures) (required) – List of pricing terms that you want to update. Supported pricing terms are:
+ **FreeTrialPricingTerm** (object) – Defines a short-term free pricing model where the buyers are not charged anything within a specified limit.
+ **Type** (string) – Type of the term being updated. This is the object value: `"FreeTrialPricingTerm"`.
+ **Duration** (string) – Duration of the free trial period.
+ **Grants** (array of structures) – Entitlements that will be granted to the acceptor of a free trial as part of an agreement execution.
+ **DimensionKey** (string) – Unique dimension key defined in the product document. Dimensions represent categories of capacity in a product and are specified when the product is listed in AWS Marketplace.
+ **MaxQuantity** (integer) (optional) – Maximum amount of capacity that the buyer can be entitled to the given dimension of the product. If `MaxQuantity` is not provided, the buyer will be able to use an unlimited amount of the given dimension.
+ **UsageBasedPricingTerm** (object) – Defines a pay-as-you-go (PAYG) pricing model where the customers are charged based on product usage.
+ **Type** (string) (required) – Category of the term being updated. This is the object value: `UsageBasedPricingTerm`.
+ **CurrencyCode** (string) – Defines the currency for prices mentioned in this term. Currently, only USD is supported.
+ **RateCards** (array of structures) – List of rate cards.
+ **RateCard** (array of structures) – A rate card defines the per-unit rates for the product dimensions.
+ **DimensionKey** (string) –Dimension that the given entitlement applies. Dimensions represent categories of capacity in a product and are specified when the product is listed in AWS Marketplace.
+ **Price** (string) – Per-unit price for the product dimension that will be used for calculating the amount to be charged to the buyer.
+ **ConfigurableUpfrontPricingTerm** (object) – Defines pre-paid payment model which allows buyers to configure the entitlements that they want to purchase and the duration of the entitlements. You can update the list of rates for each contract duration and entitlements for each dimension.
+ **Type** (string) (required) – Type of the term being updated. This is the object value: `ConfigurableUpfrontPricingTerm`.
+ **CurrencyCode** (string) (required) – Defines the currency for the prices mentioned in this term. For public offers, only USD is supported. For private offers, USD, AUD, EUR, GBP, and JPY are supported.
+ **RateCards** (array of structures) (required) – List of rate cards.
+ **Selector** (object) (required) – Selector is used to differentiate between the mutually exclusive rate cards in the same pricing term, to be selected by the buyer.
+ **Type** (string) (required) – Category of Selector. At this time, only `Duration` is supported.
+ **Value** (string) (required) – Contract duration. This field supports the ISO 8601 format.
+ **RateCard** (array of structures) (required) – A rate card defines the per-unit rates for the product dimensions.
+ **DimensionKey** (string) (required) – Unique dimension key defined in the product document. Dimensions represent categories of capacity in a product and are specified when the product is listed in AWS Marketplace.
+ **Price** (string) (required) – Per-unit price for the product dimension which will be used for calculating the amount to be charged to the buyer.
+ **Constraints** (object) (required) – Defines constraints on how the term can be configured by acceptors.
**Note**
Currently, **MultipleDimensionSelection** and **QuantityConfiguration** values need to be same.
+ **MultipleDimensionSelection** (string) (required) – Determines if buyers are allowed to select multiple dimensions in the rate card. Possible values are `Allowed` and `Disallowed`.
+ **QuantityConfiguration** (string) (required) – Determines if acceptors are allowed to configure quantity for each dimension in rate card. Possible values are `Allowed` and `Disallowed`.
+ **ByolPricingTerm** (object) – Enables you and your customers to move your existing agreements to AWS Marketplace. The customer won't be charged for product usage in AWS Marketplace because they already paid for the product outside of AWS Marketplace.
+ **Type** (string) (required) – Type of the term being updated. This is the object value: `ByolPricingTerm`.
+ **RecurringPaymentTerm** (object) – Defines a pricing model where customers are charged a fixed recurring price at the end of each billing period.
+ **Type** (string) (required) – Type of the term being updated. This is the object value: `RecurringPaymentTerm`.
+ **BillingPeriod** (string) (required) – Defines the recurrence at which buyers are charged. Only `Monthly` is supported today.
+ **Price** (string) (required) – Amount charged to the buyer every billing period.
+ **CurrencyCode** (string) (required) – Defines the currency for the prices mentioned in this term. Currently, only `USD` is supported.
+ **FixedUpfrontPricingTerm** (object) – Defines a pre-paid pricing model where the customers are charged a fixed upfront amount.
+ **Type** (string) (required) – Type of the term being updated. This is the object value: `FixedUpfrontPricingTerm`.
+ **CurrencyCode** (string) (required) – Defines the currency for the prices mentioned in this term. For public offers, only USD is supported. For private offers, USD, AUD, EUR, GBP, and JPY are supported.
+ **Price** (string) (required) – Fixed amount to be charged to the customer when this term is accepted.
+ **Grants** (array of structures) (required) – Entitlements that will be granted to the acceptor of fixed upfront as part of agreement execution.
+ **DimensionKey** (string) (required) – Unique dimension key defined in the product document. Dimensions represent categories of capacity in a product and are specified when the product is listed in AWS Marketplace.
+ **MaxQuantity** (integer) (required) – Maximum amount of capacity that the buyer can be entitled to the given dimension of the product. If `MaxQuantity` is not provided, the buyer will be able to use an unlimited amount of the given dimension.
+ **Duration** (string) (optional) – Defines the duration that the term remains active. This field supports the ISO 8601 format.
**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 a few minutes.
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 `UpdatePricingTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP |
| --- | --- | --- |
| PricingModel | RequiredAllowed pricing models: ["Byol", "Free", "Usage", "Contract"] | 422 |
| Terms | RequiredAllowed Terms: ["ConfigurableUpfrontPricingTerm", "ByolPricingTerm", "FreeTrialPricingTerm", "UsageBasedPricingTerm", "RecurringPaymentTerm", "FixedUpfrontPricingTerm"] | 422 |
| Terms[].ByolPricingTerm | Required | 422 |
| Terms[].ByolPricingTerm.Type | RequiredCan only be "ByolPricingTerm" | 422 |
| Terms[].ConfigurableUpfrontPricingTerm | Required | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.Type | RequiredCan only be "ConfigurableUpfrontPricingTerm" | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.CurrencyCode | RequiredSupported currencies: ["USD", "AUD", "EUR", "GBP", "JPN"] | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards | RequiredList size must be between 1 and 5 | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].Constraints | Required | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].Contraints.MultipleDimensionSelection | RequiredAllowed values: ["Allowed", "Disallowed"] | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].Contraints.QuantityConfiguration | RequiredAllowed values: ["Allowed", "Disallowed"] | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].RateCard | RequiredList size must be between 1 and 800 | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].RateCard[].DimensionKey | RequiredLength must be between 1 and 100 | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].RateCard[].Price | RequiredData type is "String"Non-negative decimals with up to 3 decimal places supported | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].Selector | Required | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].Selector.Type | RequiredAllowed values: ["Duration"] | 422 |
| Terms[].ConfigurableUpfrontPricingTerm.RateCards[].Selector.Value | RequiredExpected format per Selector type: ISO 8601 duration | 422 |
| Terms[].FixedUpfrontPricingTerm | Required | 422 |
| Terms[].FixedUpfrontPricingTerm.Type | RequiredCan only be "FixedUpfrontPricingTerm" | 422 |
| Terms[].FixedUpfrontPricingTerm.CurrencyCode | RequiredSupported currencies: ["USD", "AUD", "EUR", "GBP", "JPN"] | 422 |
| Terms[].FixedUpfrontPricingTerm.Duration | RequiredExpected format per Selector type: ISO 8601 duration | 422 |
| Terms[].FixedUpfrontPricingTerm.Grants | RequiredList size must be between 1 and 200 | 422 |
| Terms[].FixedUpfrontPricingTerm.Grants[].DimensionKey | RequiredLength must be between 1 and 100 | 422 |
| Terms[].FixedUpfrontPricingTerm.Grants[].MaxQuantity | RequiredValue must be greater than 0 | 422 |
| Terms[].FixedUpfrontPricingTerm.Price | RequiredData type is "String"Non-negative decimals with up to 3 decimal places supported | 422 |
| Terms[].FreeTrialPricingTerm | Required | 422 |
| Terms[].FreeTrialPricingTerm.Type | RequiredCan only be "FreeTrialPricingTerm" | 422 |
| Terms[].FreeTrialPricingTerm.Duration | RequiredExpected format: ISO 8601 duration | 422 |
| Terms[].FreeTrialPricingTerm.Grants | RequiredList size must be between 1 and 800 | 422 |
| Terms[].FreeTrialPricingTerm.Grants[].DimensionKey | RequiredLength must be between 1 and 100 | 422 |
| Terms[].FreeTrialPricingTerm.Grants[].MaxQuantity | OptionalValue must be greater than 0 | 422 |
| Terms[].RecurringPaymentTerm | Required | 422 |
| Terms[].RecurringPaymentTerm.Type | RequiredCan only be "RecurringPaymentTerm" | 422 |
| Terms[].RecurringPaymentTerm.BillingPeriod | RequiredAllowed values: ["Monthly"] | 422 |
| Terms[].RecurringPaymentTerm.CurrencyCode | RequiredSupported currencies: ["USD"] | 422 |
| Terms[].RecurringPaymentTerm.Price | RequiredData type is "String"Non-negative decimals with up to 3 decimal places supported | 422 |
| Terms[].UsageBasedPricingTerm | Required | 422 |
| Terms[].UsageBasedPricingTerm.Type | RequiredCan only be "UsagedBasedPricingTerm" | 422 |
| Terms[].UsageBasedPricingTerm.CurrencyCode | RequiredSupported currencies: ["USD"] | 422 |
| Terms[].UsageBasedPricingTerm.RateCards | RequiredMust be size of 1 | 422 |
| Terms[].UsageBasedPricingTerm.RateCards[].RateCard | RequiredList size must be between 1 and 800 | 422 |
| Terms[].UsageBasedPricingTerm.RateCards[].RateCard[].DimensionKey | RequiredLength must be between 1 and 100 | 422 |
| Terms[].UsageBasedPricingTerm.RateCards[].RateCard[].Price | RequiredData type is "String"Non-negative decimals with up to 8 decimal places supported | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdatePricingTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| DUPLICATE\$1DIMENSION\$1KEYS | Provide Grants with a unique list of dimension keys in [x]. |
| DUPLICATE\$1DIMENSION\$1KEYS | Provide RateCard with a unique list of dimension keys in [x]. |
| DUPLICATE\$1SELECTORS | Provide a unique list of Selectors in ConfigurableUpfrontPricingTerm. |
| DUPLICATE\$1TERM\$1TYPES | Provide a unique list of term types. |
| INCOMPATIBLE\$1AGREEMENT | The following terms can't be removed from the replacement offer: [x, y, z]. |
| INCOMPATIBLE\$1AGREEMENT | The following terms can't be added to the replacement offer: [x, y, z]. |
| INCOMPATIBLE\$1CURRENCY\$1CODE | CurrencyCode can't be changed after the offer is released. |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1PRODUCT | Usage pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | Contract pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | Byol pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | Free pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | [x] isn't supported in an offer for the product. |
| INCOMPATIBLE\$1PRODUCT | Provided payment and pricing terms are incompatible. |
| INCOMPATIBLE\$1PRODUCT | Use existing, available dimensions in the product in [x]. |
| INCOMPATIBLE\$1PRODUCT | FreeTrialPricingTerm as the offer's only pricing term isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | The following terms aren't supported for the product: [x,y,z]. |
| INCOMPATIBLE\$1PRODUCT | Replacement offers are only supported for contract pricing model. |
| INCOMPATIBLE\$1PRODUCT | Provide pricing term(s) that are compatible with the product dimensions. Incompatible pricing terms: [x,y,z]. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | Set MultipleDimensionSelection and QuantityConfiguration to Allowed in ConfigurableUpfrontPricingTerm for usage pricing model. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | Set MultipleDimensionSelection and QuantityConfiguration to Disallowed in ConfigurableUpfrontPricingTerm for usage pricing model. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | QuantityConfiguration in ConfigurableUpfrontPricingTerm can't be changed after the offer is released. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | MultipleDimensionSelection in ConfigurableUpfrontPricingTerm can't be changed after the offer is released. |
| INCOMPATIBLE\$1RATES | Set all charge amounts and prices to zero (0) when using Free pricing model. |
| INCOMPATIBLE\$1RATES | Only zero (0) prices are allowed in UsageBasedPricingTerm for a free trial offer for the product. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide the same CurrencyCode that is specified in the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure Duration in FixedUpfrontPricingTerm matches duration specified in the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide term(s) that are compatible with the ResaleAuthorization. Incompatible terms: [x, y, z]. |
| INCOMPATIBLE\$1SELECTOR\$1DURATION | Durations aren't allowed to be removed from rate cards in ConfigurableUpfrontPricingTerm after the offer released. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INCOMPATIBLE\$1TERMS | [x] isn't supported together with the following terms: [y,z]. |
| INCOMPATIBLE\$1TERMS | The following terms can't be added after the offer is released: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | The following terms can't be removed after the offer is released: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | [x] isn't supported for private offers. |
| INCOMPATIBLE\$1TERMS | The following terms aren't supported with FreeTrialPricingTerm that grants unlimited usage: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | The following terms aren't supported with FreeTrialPricingTerm for the product: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | Provide zero (0) price for FixedUpfrontPricingTerm when the offer contains a PaymentScheduleTerm. |
| INCOMPATIBLE\$1TERMS | The following terms aren't compatible with the PricingModel: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | FixedUpfrontPricingTerm isn't supported when MarkupPercentage is greater than zero (0). |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1AGREEMENT\$1DURATION | Provide duration between [x] and [y] months. |
| INVALID\$1AGREEMENT\$1DURATION | Ensure duration granularity is at the day level for metered dimensions. |
| INVALID\$1CURRENCY\$1CODE | Provide a supported CurrencyCode. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| INVALID\$1CURRENCY\$1CODE | Provide a supported CurrencyCode. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| INVALID\$1DURATION | Ensure Duration in FreeTrialPricingTerm is within the allowed range. |
| INVALID\$1DURATION | Provide Duration in FixedUpfrontPricingTerm that matches the duration between AgreementStartDate and AgreementEndDate. |
| INVALID\$1DURATION | Provide duration between [x] and [y] months. |
| INVALID\$1DURATION | Ensure duration granularity is at the day level for metered dimensions. |
| INVALID\$1GRANTS | Provide the same MaxQuantity for all Grants in FreeTrialPricingTerm. |
| INVALID\$1GRANTS | Provide Grants for all available metered dimensions in FreeTrialPricingTerm. |
| INVALID\$1GRANTS | The combination of Dimensions in grants is invalid in FixedUpfrontPricingTerm for the product. |
| INVALID\$1GRANTS | The combination of Dimensions in grants is invalid in FreeTrialPricingTerm for the product. |
| INVALID\$1GRANTS | FixedUpfrontPricingTerm with MaxQuantity is not supported for this product. |
| INVALID\$1PRICE\$1CHANGE | [x] can't be updated until [y] because you have requested a price increase in the past 120 days. To cancel your previous price increase request or for more information, contact the AWS Marketplace Managed Catalog Operations Team. |
| INVALID\$1PRICE\$1CHANGE | Price increase and dimension addition in [x] isn't supported in the same request. Add dimensions first. |
| INVALID\$1PRICE\$1CHANGE | Price increase and decrease in UsageBasedPricingTerm isn't supported in the same request. Decrease prices first. |
| INVALID\$1PRICE\$1CHANGE | Price increase in RecurringPaymentTerm and price decrease in UsageBasedPricingTerm isn't supported in the same request. Decrease prices first. |
| INVALID\$1PRICE\$1CHANGE | Price decrease in RecurringPaymentTerm and price increase in UsageBasedPricingTerm isn't supported in the same request. Decrease prices first. |
| INVALID\$1RATE\$1CARD | ConfigurableUpfrontPricingTerm is missing one or more-dimension keys for duration [x]. Provide prices for the same set of dimension keys for all durations. |
| INVALID\$1RATE\$1CARD | Provide a rate card for only metered dimensions in UsageBasedPricingTerm. |
| INVALID\$1RATE\$1CARD | Rates can't be removed from [x]. Provide prices for all dimensions in the existing rate card. |
| INVALID\$1RATE\$1CARD | Provide dimensions that have the same unit in [x]. |
| INVALID\$1RATE\$1CARD | Provide either all metered or all entitled dimensions in [x]. |
| INVALID\$1RATE\$1CARD | Provide only entitled dimensions in [x]. |
| INVALID\$1RATE\$1CARD | Provide usage based rates for all available metered dimensions in UsageBasedPricingTerm. |
| INVALID\$1RATE\$1CARD | Provide usage based rates for all free trial dimensions. |
| INVALID\$1RATE\$1CARD | Provide prices with up to 8 decimal places in UsageBasedPricingTerm. |
| INVALID\$1RATE\$1CARD | The combination of Dimensions in rate card is invalid in UsageBasedPricingTerm for the product. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide duration between [x] and [y] months. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Ensure duration granularity is at the day level for metered dimensions. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Ensure Duration in ConfigurableUpfrontPricingTerm is within the allowed range. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide one or more supported contract durations. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide one or more supported contract durations or a single custom duration. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide Duration in ConfigurableUpfrontPricingTerm that matches the duration between AgreementStartDate and AgreementEndDate. |
| MISSING\$1DURATION | Provide Duration in FixedUpfrontPricingTerm. |
| MISSING\$1MANDATORY\$1TERMS | FixedUpfrontPricingTerm is only supported when paired with ByolPricingTerm or PaymentScheduleTerm. |
| MISSING\$1MANDATORY\$1TERMS | Provide at least one of [x,y,z]. |
| MISSING\$1MANDATORY\$1TERMS | Provide a ByolPricingTerm when using Byol pricing model. |
| TOO\$1MANY\$1GRANTS | Provide up to [x] grants in [y]. |
| TOO\$1MANY\$1RATE\$1CARDS | Only one rate card in ConfigurableUpfrontPricingTerm is allowed for the product. |
| TOO\$1MANY\$1RATE\$1CARDS | Up to [x] rate cards are allowed in ConfigurableUpfrontPricingTerm for the product. |
| TOO\$1MANY\$1RATES | Provide RateCards within the allowed limits in ConfigurableUpfrontPricingTerm. |
| TOO\$1MANY\$1RATES | Provide RateCards within the allowed limits in UsageBasedPricingTerm. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | Set both MultipleDimensionSelection and QuantityConfiguration to the same value (Allowed or Disallowed) in ConfigurableUpfrontPricingTerm. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | Provide the same constraints for all rate cards in ConfigurableUpfrontPricingTerm. |
| INVALID\$1UPDATE\$1REQUEST | [x] can't be updated. To request pricing change or for more information, contact the AWS Marketplace Managed Catalog Operations Team. |
| INCOMPATIBLE\$1PRICING\$1MODEL | PricingModel can't change from [x] to [y]. |
| INVALID\$1GRANTS | MaxQuantity for the FreeTrialPricingTerm is limited for the product. Provide a MaxQuantity less than or equal to [x]. For more information, contact the AWS Marketplace Managed Catalog Operations Team. |
| INVALID\$1GRANTS | Provide MaxQuantity for all Grants in FixedUpfrontPricingTerm. |
| INVALID\$1GRANTS | MaxQuantity isn't supported in FixedUpfrontPricingTerm for the product. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure Grants in FixedUpfrontPricingTerm matches RateCards specified in the ResaleAuthorization. |
## Update the discoverability of the offer
You can use the Catalog API to control the discoverability of your offer in AWS Marketplace.
You can either choose to set a specific date in the future to restrict the discoverability of your offer or in the past to expire your offer. The `UpdateAvailability` change type doesn’t affect existing agreements.
**Note**
You can use the `UpdateAvailability` change type on a private offer that has already been [published](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#release-offer) (also known as *released*). If buyers have already accepted the private offer, those existing agreements aren't affected.
When modifying the `AvailabilityEndDate` of an existing private offer, the [constraints of the agreement duration](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#update-validity-terms) must be adhered to. If it's not, include an additional `UpdateValidityTerms` change type in this change set to modify the agreement duration to adhere to the new expiration. The `UpdateValidityTerms` change type can be used on a private offer that is either released or not yet released.
When modifying the `AvailabilityEndDate` of an existing private offer, the [constraints of the payment schedule](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#update-payment-schedule-terms) must be adhered to. If it's not and the private offer is *not yet released*, include an additional `UpdatePaymentScheduleTerms` change type in this change set to modify the payment schedule to adhere to the new expiration. If the private offer is *already released*, you can only make changes to the `AvailabilityEndDate` as long as the new date adheres to the constraints of the payment schedule.
To control the discoverability of your offer, call the `StartChangeSet` API operation with the `UpdateAvailability` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateAvailability",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"AvailabilityEndDate": "2024-05-31"
}
}
]
}
```
Provide information for the fields to add the `UpdateAvailability` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **AvailabilityEndDate** (string) (required) – This is the date until when the offer is discoverable and purchasable in AWS Marketplace. You can choose to set a specific date in the future to restrict the availability or in the past to expire the offer. Dates are represented in `YYYY-MM-DD` format.
A change set is created for your request. The response to this request gives you the ID and ARN for the change set and looks like the following.
**Response Syntax**
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef"
}
```
The change request is added to a queue and processed. It includes validating information to ensure that it meets the AWS Marketplace guidelines. The validation process can take a few minutes. You can check the status of the request through the AWS Marketplace Management Portal, or in the Catalog API with the `DescribeChangeSet` action.
**Synchronous Validations**
The following schema validations are specific to `UpdateAvailability` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| AvailabilityEndDate | Required Format: "YYYY-MM-DD" | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateAvailability` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more details about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1AVAILABILITY\$1END\$1DATE | AvailabilityEndDate isn't supported for public offers. |
| INVALID\$1AVAILABILITY\$1END\$1DATE | Provide a future AvailabilityEndDate. |
| INVALID\$1AVAILABILITY\$1END\$1DATE | Provide an AvailabilityEndDate that is before AgreementEndDate. |
| MISSING\$1AVAILABILITY\$1END\$1DATE | Provide an AvailabilityEndDate that is before the agreement's end date. |
## Define the expiration date of agreements created using the offer
You can use the Catalog API to define the expiration date details of agreements created using the offer in AWS Marketplace.
This change type doesn’t affect existing agreements.
**Note**
You can use the `UpdateValidityTerms` change type on a private offer that has already been [published](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#release-offer) (also known as *released*). If buyers have already accepted the private offer, those existing agreements aren't affected.
For **AMI-based** and **container-based** products, if your private offer [pricing terms](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#update-pricing-terms) include a term type that has a `Duration` (for example, the term types `FixedUpfrontPricingTerm` or `ConfigurableUpfrontPricingTerm`), your `AgreementDuration` set in this change type must be greater than the following: the number of days from today to the [expiration of the private offer](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#update-availability) plus the number of days set in the `Duration` of those term types. This is because after a buyer accepts the private offer and the agreement is created, they can optionally purchase additional entitlements specified in those term types until the private offer expires. Furthermore, all additional entitlements must end before the agreement does. For example, if the buyer accepts the private offer on the first available day and then purchases entitlements on the last available day, those entitlements must not end after the agreement end date.
To define the expiration date details of agreements created using the offer, call the `StartChangeSet` API operation with the `UpdateValidityTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateValidityTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "ValidityTerm",
"AgreementDuration": "P12M",
"AgreementStartDate": "2021-08-01",
"AgreementEndDate": "2022-08-01"
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateValidityTerms` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Terms** (array of structures) – List of validity terms that you want to update. Supported validity terms are:
+ **ValidityTerm** (object) – Defines the conditions that will keep an agreement, created from this offer, valid.
+ **Type** (string) – Category of the term being updated. `ValidityTerm`
+ **AgreementDuration** (string) – Defines the duration that the agreement remains active. If `AgreementStartDate` isn’t provided, agreement duration is relative to the agreement signature time. The duration is represented in the ISO\$18601 format.
+ **AgreementStartDate** (string) – Defines the date when agreement starts. `AgreementStartDate` is represented in `YYYY-MM-DD` format. The agreement starts at 00:00:00.000 UTC on the date provided. If `AgreementStartDate` isn’t provided, agreement start date is determined based on agreement signature time.
+ **AgreementEndDate** (string) – Defines the date when the agreement ends. The `AgreementEndDate` is represented in `YYYY-MM-DD` format. The agreement ends at 23:59:59.999 UTC on the date provided. If `AgreementEndDate` isn’t provided, the agreement end date is determined by the validity of individual terms.
**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 a few minutes.
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 `UpdateValidityTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Terms | Required | 422 |
| Terms[].Type | Required Can only be `"ValidityTerm"` | 422 |
| Terms[].AgreementDuration | Optional Expected format per Selector type: ISO 8601 duration Can be stand alone or paired with `AgreementStartDate` | 422 |
| Terms[].AgreementEndDate | Optional Date must be formatted like `"YYYY-MM-DD"` | 422 |
| Terms[].AgreementStartDate | Optional Date must be formatted like `"YYYY-MM-DD"` Can only be paired with `AgreementEndDate` and `AgreementDuration` | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateValidityTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1AGREEMENT | AgreementStartDate can't be in the future when the current agreement to be replaced isn't future dated. |
| INCOMPATIBLE\$1AGREEMENT\$1END\$1DATE | AgreementEndDate can't be updated after the offer is released. |
| INCOMPATIBLE\$1AGREEMENT\$1START\$1DATE | AgreementStartDate can't be updated after the offer is released. |
| INCOMPATIBLE\$1PRODUCT | AgreementStartDate in the future isn't supported. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the duration between AgreementStartDate and AgreementEndDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure AgreementStartDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure AgreementEndDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the duration between AgreementStartDate and AgreementEndDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure AgreementDuration matches duration specified in the ResaleAuthorization. |
| INCOMPATIBLE\$1TERMS | ValidityTerm isn't supported for public offers. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1AGREEMENT\$1DURATION | Provide AgreementDuration that is greater than or equal to [x] days. |
| INVALID\$1AGREEMENT\$1END\$1DATE | Provide a future AgreementEndDate. |
| INVALID\$1AGREEMENT\$1END\$1DATE | Provide AgreementEndDate that is after or equal to [x]. |
| INVALID\$1AGREEMENT\$1START\$1DATE | Provide an AgreementStartDate that is after AvailabilityEndDate. |
| INVALID\$1AGREEMENT\$1START\$1DATE | Provide an AgreementStartDate that is before the AgreementEndDate. |
| INVALID\$1AGREEMENT\$1START\$1DATE | Provide an AgreementStartDate that is within [x] years from today. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with both AgreementDuration and AgreementEndDate isn't supported. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with both AgreementStartDate and AgreementDuration isn't supported in an offer for the product. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with AgreementStartDate isn't supported in an offer for the product. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with only AgreementStartDate isn't supported. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | AgreementEndDate isn't supported unless it's used in combination with a future AgreementStartDate or for replacement offers. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | Provide AgreementStartDate and AgreementEndDate where the difference is less than or equal to [x] years. |
| MISSING\$1AGREEMENT\$1START\$1DATE | Ensure AgreementStartDate is present in ValidityTerm when used along with ConfigurableUpfrontPricingTerm. |
| INVALID\$1AGREEMENT\$1END\$1DATE | Provide an AgreementEndDate that is within [x] years from today. |
| INCOMPATIBLE\$1AGREEMENT\$1START\$1DATE | Provide the same AgreementStartDate as defined in the agreement when the agreement has a future start date. |
| INCOMPATIBLE\$1AGREEMENT | AgreementStartDate can't be future dated when the agreement isn't future dated. |
## Update payment schedule details
You can use the Catalog API to update payment schedule details for your offer, such as flexible payment schedule, in AWS Marketplace.
**Note**
You cannot use the `UpdatePaymentScheduleTerms` change type on an offer that has already been [published](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#release-offer) (also known as *released*).
The private offer can be accepted any day between the creation of the private offer and its [expiration](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#update-availability) (set in the `AvailabilityEndDate`). Only one `ChargeDate` value of the payment schedule can be a date on or before the last day the buyer can accept the private offer (the private offer expiration date). The remaining values of `ChargeDate` must be after the private offer expiration, but no later than the end of the agreement if the private offer was accepted immediately. The end of the agreement is based on when the private offer is accepted (creating the agreement) plus the [duration of the agreement](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/offers.html#update-validity-terms).
To update payment schedule details for your offer, call the `StartChangeSet` API operation with the `UpdatePaymentScheduleTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdatePaymentScheduleTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "PaymentScheduleTerm",
"Schedule": [
{
"ChargeDate": "2021-12-01",
"ChargeAmount": "200.00"
},
{
"ChargeDate": "2022-03-01",
"ChargeAmount": "250.00"
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdatePaymentScheduleTerms` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Terms** (array of structures) – List of payment terms that you want to update. Supported payment terms are:
+ **PaymentScheduleTerm** (object) – Defines an installment-based pricing model where customers are charged a fixed price on different dates during the agreement validity period.
+ **Type** (string) – Type of the term being updated. This is the object value: `"PaymentScheduleTerm"`.
+ **Schedule** (array of structures) – List of the payment schedule where each element defines one installment of payment. It contains the information necessary for calculating the price to be paid and the date on which the customer would be charged.
+ **ChargeDate** (string) – The date on which the customer would pay the price defined in this payment schedule term. `ChargeDate` is represented in YYYY-MM-DD format. Invoices are generated on the date provided.
+ **ChargeAmount ** (string) – The price that the customer would pay on scheduled date (`ChargeDate`).
**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 a few minutes.
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 `UpdatePaymentScheduleTerms` 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 will fail with an HTTP response.
| Input Field | Validation Rule | HTTP |
| --- | --- | --- |
| Terms | Required Only `PaymentScheduleTerm` is allowed List size must be less than 2 | 422 |
| Terms[].Type | Required Can only be `PaymentScheduleTerm` | 422 |
| Terms[].PaymentScheduleTerm.CurrencyCode | Required Supported currencies: ["USD", "AUD", "EUR", "GBP", "JPY"] | 422 |
| Terms[].PaymentScheduleTerm.Schedule[] | Required | 422 |
| Terms[].PaymentScheduleTerm.Schedule[].ChargeAmount | RequiredDate type is "String"Non-negative decimals with up to 2 decimal places supported | 422 |
| Terms[].PaymentScheduleTerm.Schedule[].ChargeDate | Required Date must be formatted like "YYYY-MM-DD" | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdatePaymentScheduleTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| DUPLICATE\$1CHARGE\$1DATES | Provide unique charge dates in PaymentScheduleTerm. |
| INCOMPATIBLE\$1CURRENCY\$1CODE | CurrencyCode can't be changed after the offer is released. |
| INCOMPATIBLE\$1MARKUP\$1PERCENTAGE | PaymentScheduleTerm isn't supported when MarkupPercentage is greater than zero (0). |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide term(s) that are compatible with the ResaleAuthorization. Incompatible terms: [PaymentScheduleTerm]. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the total ChargeAmounts in PaymentScheduleTerm is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1CHARGE\$1DATES | Provide charge dates before AgreementEndDate. |
| INVALID\$1CURRENCY\$1CODE | Provide a supported CurrencyCode. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| TOO\$1MANY\$1BACKDATED\$1CHARGES | Provide up to 1 scheduled payment before AvailabilityEndDate. |
| INVALID\$1CHARGE\$1DATES | Provide a last charge date that is before AgreementEndDate. |
| INVALID\$1CHARGE\$1DATES | Provide a first charge date that isn't in the past. |
| TOO\$1MANY\$1CHARGES | Provide up to [x] scheduled payments in PaymentScheduleTerm. |
## Modify renewal options
You can use the Catalog API to control renewal options of the agreements that are created using this offer in AWS Marketplace.
For offers created through Catalog API, auto-renewal remains disabled by default until you call the `UpdateRenewalTerms` change type to allow auto-renewal. This change does not affect existing agreements.
To control renewal options of the agreements that are created using this offer, call the `StartChangeSet` API operation with the `UpdateRenewalTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateRenewalTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "RenewalTerm"
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateRenewalTerms` change type:
+ **Entity** (object) (required) – Your offer.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Terms** (array of structures) – List of renewal terms that you want to update. Supported renewal terms are:
+ **RenewalTerm** (object) – Defines that on graceful termination (expiration of the `ValidityTerm`, not buyer or AWS Marketplace cancellation) of the agreement, a new agreement will be created using the accepted terms on the existing agreement. In other words, the agreement will be renewed. Presence of `RenewalTerm` in the offer means that auto-renewal is allowed. Buyers will have the option to accept or decline auto-renewal at the offer acceptance/agreement creation.
+ **Type** (string) – Type of the term being updated. `RenewalTerm`
**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 a few minutes.
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 `UpdateRenewalTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Terms | Required | 422 |
| Terms[].Type | RequiredCan only be "RenewalTerm" | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateRenewalTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more details about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT | RenewalTerm isn't supported in private offers for the product. |
| INCOMPATIBLE\$1TERMS | RenewalTerm isn't supported together with PaymentScheduleTerm. |
| INCOMPATIBLE\$1TERMS | RenewalTerm isn't supported with the PricingModel. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
## Publish an offer
You can use the Catalog API to merge the information collected from all update change types, and then publish the offer.
Offers remain in a `Draft` state, until `ReleaseOffer` is called. After the offer is released, it’s discoverable in AWS Marketplace.
To publish your offer, call the `StartChangeSet` API operation with the `ReleaseOffer` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "ReleaseOffer",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {}
}
]
}
```
Provide information for the fields to add the `ReleaseOffer` change type:
+ **Entity** (object) – The named type of entity being created. The `Identifier` is your offer ID, and the `Type` is always `Offer@1.0`. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) – The JSON value of specifics of the request. It must be empty for `ReleaseOffer`.
**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 a few minutes.
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 `ReleaseOffer` 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 will fail with an HTTP response.
| Input field | Validation rule |
| --- | --- |
| DetailsDocument | Must be empty (\$1\$1) |
**Asynchronous Errors**
The following errors are specific to `ReleaseOffer` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1PRODUCT | First create a public offer for the product. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INCOMPATIBLE\$1TARGETING | PreExistingAgreement is only supported for buyer targeted offers. |
| INCOMPATIBLE\$1TARGETING | OfferSetId is only supported for buyer targeted offers. |
| INVALID\$1TAX\$1INFORMATION | Your tax information is incomplete. To sell professional services on AWS Marketplace, you must complete the DAC7 tax questionnaire. Navigate to the Payment Information section, and select the DAC7 tax form. It can take up to two hours for your tax information to update. |
| INVALID\$1UPDATE\$1REQUEST | The requested change can't be performed after the offer is released. |
| MISSING\$1AGREEMENT\$1END\$1DATE | Provide an AgreementEndDate for replacement offers. |
| MISSING\$1AVAILABILITY\$1END\$1DATE | Provide an AvailabilityEndDate for private offer. |
| MISSING\$1BUYER\$1ACCOUNTS | Provide PositiveTargeting with BuyersAccounts for offers created using ResaleAuthorization. |
| MISSING\$1BUYER\$1ACCOUNTS | All offers for the product must be private. Provide PositiveTargeting with BuyersAccounts. |
| MISSING\$1DESCRIPTION | Set Description before releasing the offer. |
| MISSING\$1MANDATORY\$1TERMS | Add [x] to the offer. |
| MISSING\$1MANDATORY\$1TERMS | Provide a FixedUpfrontPricingTerm when the offer contains a PaymentScheduleTerm. |
| MISSING\$1NAME | Set Name before releasing the offer. |
| TOO\$1MANY\$1OFFERS | Only one public free trial offer can be created per product. |
| TOO\$1MANY\$1OFFERS | Only one public offer can be created per product. |
| MISSING\$1MANDATORY\$1TERMS | Provide a RenewalTerm for public offers with contract pricing for the product. |
| MISSING\$1AGREEMENT\$1END\$1DATE | Provide an AgreementEndDate for replacement offers. |
## Describe existing offer details
You can use the Catalog API to describe existing offer details in AWS Marketplace.
To describe existing offer details, call the `DescribeEntity` API operation with the `Offer@1.0` entity type, as shown in the following example.
**Request Syntax**
```
GET /DescribeEntity?catalog=&entityId= HTTP/1.1
```
Provide information for the fields to add the `DescribeEntity` change type:
+ **catalog** (string) – The catalog related to the request. Fixed value: `AWSMarketplace`.
+ **entityId** (string) – The unique ID of the offer to describe.
**Response Syntax**
The response to this request gives you the offer details and looks like the following.
```
{
"EntityType": "Offer@1.0",
"EntityIdentifier": "offer-ad8EXAMPLE51@1",
"EntityArn": "arn:aws:aws-marketplace:us-east-1:111122223333:AWSMarketplace/Offer/offer-ad8EXAMPLE51",
"LastModifiedDate": "2021-03-10T21:57:16Z",
"DetailsDocument": {
"Id": "offer-3rEXAMPLErn",
"State": "Released",
"Name": "Test Offer",
"Description": "Worldwide offer for Test Product",
"PreExistingAgreement": {
"AcquisitionChannel": "External",
"PricingModel": "Contract"
},
"ProductId": "prod-ad8EXAMPLE51",
"OfferSetId": "offerset-b3f9EXAMPLE27",
"Terms": [
{
"Type": "SupportTerm",
"RefundPolicy": "If you need to request a refund for software sold by Amazon Web Services, LLC, please contact AWS Customer Service."
},
{
"Type": "LegalTerm",
"Documents": [
{
"Type": "CustomEula",
"Url": "https://s3.amazonaws.com/EULA/custom-eula-1234.txt"
}
]
},
{
"Type": "FreeTrialPricingTerm",
"Duration": "P30D",
"Grants": [
{
"DimensionKey": "m3.xlarge",
"MaxQuantity": 10
},
{
"DimensionKey": "m4.xlarge",
"MaxQuantity": 10
}
]
},
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P365D"
},
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "300.00"
},
{
"DimensionKey": "m4.xlarge",
"Price": "400.00"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
},
{
"Type": "UsageBasedPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "0.10"
},
{
"DimensionKey": "m4.xlarge",
"Price": "0.20"
}
]
}
]
},
{
"Type": "FixedUpfrontPricingTerm",
"CurrencyCode": "USD",
"Price": "200.00",
"Grants": [
{
"DimensionKey": "Users",
"MaxQuantity": 10
}
]
},
{
"Type": "RecurringPaymentTerm",
"CurrencyCode": "USD",
"BillingPeriod": "Monthly",
"Price": "100.0"
},
{
"Type": "PaymentScheduleTerm",
"CurrencyCode": "USD",
"Schedule": [
{
"ChargeDate": "2020-12-01T00:00:00.000Z",
"ChargeAmount": "1000.00"
},
{
"ChargeDate": "2021-06-15T00:00:00.000Z",
"ChargeAmount": "1250.00"
}
]
},
{
"Type": "ByolPricingTerm"
},
{
"Type": "RenewalTerm"
}
],
"Rules": [
{
"Type": "TargetingRule",
"PositiveTargeting": {
"CountryCodes": [
"US",
"CA"
],
"BuyerAccounts": [
"444455556666"
]
},
"NegativeTargeting": {
"CountryCodes": [
"XX"
]
}
},
{
"Type": "AvailabilityRule",
"AvailabilityEndDate": "2024-08-30T01:56:03.000Z"
}
]
}
}
```
The following is information about the fields you see in the `DescribeEntity` response.
+ **EntityType** (string) – The named type of the entity, which is `Offer@1.0`.
+ **EntityIdentifier** (string) – The identifier of the entity, in the format of `EntityId@RevisionId`.
+ **EntityArn** (string) – The ARN associated to the unique identifier for the change set referenced in this request.
+ **LastModifiedDate** (string) –The last modified date of the entity, in ISO 8601 format (for example: `2018-02-27T13:45:22Z`).
+ **Details** (string) – This stringified JSON object includes the following details of the entity:
+ **Id** (string) – Unique identifier for an offer entity in AWS Marketplace and is generated during the creation of an offer.
+ **State** (string) – The status of the offer.
+ **Name** (string) – The name associated with the offer for better readability to you and your customers. It will be displayed as part of Agreement information as well.
+ **Description** (string) – Description is a free-form text which is meant to be used only by you and will never be exposed to buyers.
+ **PreExistingAgreement** (string) – 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) – Indicates if the existing agreement was signed outside AWS Marketplace or within AWS Marketplace. Possible values: `External`, `AwsMarketplace`.
+ **PricingModel** (string) – Indicates which pricing model the existing agreement uses. Possible values: `Contract`, `Usage`, `Byol`, `Free`.
+ **ProductId** (string) – The unique identifier of the product being offered.
+ **OfferSetId** (string) – The unique identifier of the offer set to associate this offer with.
+ **Terms** (array of structures) – List of terms.
+ **Rules** (array of structures) – List of rules.
# Work with resale authorizations using the AWS Marketplace APIs
You can use the AWS Marketplace Catalog API to automate tasks for working with Resale Authorizations.
While the *product* describes what is being sold in AWS Marketplace, the *Resale Authorization* (also known as an opportunity) describes the terms and rules regarding how this product is authorized to be resold in AWS Marketplace. The *CPPO* is the target of the Resale Authorization.
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.
There are two types of rules in a Resale Authorization:
+ **AvailabilityRule** – Controls the lifecycle of the Resale Authorization in AWS Marketplace.
+ **PartnerTargetingRule ** – Specifies whether the Resale Authorization should be accessible to a specific set of channel partners.
See the following resources:
+ For end-to-end labs with working code examples, see [Lab: Authorize a reseller](https://catalog.workshops.aws/mpseller/en-US/manage-offers-with-api/authorize-a-reseller) in the *AWS Marketplace seller workshop*.
+ 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 a video on creating resale authorizations, see [Create Resale Authorizations Using the AWS Marketplace Catalog API](https://www.youtube.com/watch?v=vLIbvFYI974) on YouTube.
The following topics describe how to use the Catalog API to create and update Resale Authorizations:
**Topics**
+ [
## Resale Authorization prerequisites
](#prerequisites)
+ [
## Create a new Resale Authorization
](#create-resale-authorization)
+ [
## Update buyer targeting
](#update-buyer-targeting)
+ [
## Update availability
](#update-availability-resale-auth)
+ [
## Update the validity of a future dated agreement
](#update-validity-fda)
+ [
## Update legal resources
](#update-existing-legal-terms)
+ [
## Update pricing
](#update-existing-pricing-terms)
+ [
## Update payment schedule
](#update-payment-schedule-details)
+ [
## Update Resale Authorization details
](#update-resale-auth-information)
+ [
## Restrict a Resale Authorization
](#restricte-resale-auth)
+ [
## Release a Resale Authorization and make it visible to a Channel Partner
](#release-resale-auth)
+ [
## Describe an existing Resale Authorization
](#describe-entity-resale-auth)
## Resale Authorization prerequisites
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*.
## Create a new Resale Authorization
You can use the Catalog API to create a new Resale Authorization 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 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 your it visible to channel partners in AWS Marketplace.
To create a Resale Authorization in `Draft` state, call the `StartChangeSet` API operation with the `CreateResaleAuthorization` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "CreateResaleAuthorization",
"ChangeName": "xyz",
"Entity":
{
"Type": "ResaleAuthorization@1.0"
},
"DetailsDocument":
{
"ProductId": "prod-ad8EXAMPLE51",
"Name": "Test ResaleAuthorization",
"Description": "Worldwide ResaleAuthorization for Test Product",
"ResellerAccountId": "777788889999"
}
}
]
}
```
Provide information for the input fields to add the `CreateResaleAuthorization` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **DetailsDocument** (object) (required) – Specifics of the request.
+ **ProductId** (string) (required) – Product ID for which to create the resale authorization.
+ **Name** (string) (required) – Name associated with the ResaleAuthorization for better readability to you and your channel partners.
+ **Description** (string) (optional) – A free-form text field available to add details about the ResaleAuthorization.
+ **ResellerAccountId** (string) (required) – Add targeted channel partner’s AWS account who can describe and use this `ResaleAuthorization` to create a private offer.
**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.
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.
When the request is complete (if the `Status` is `SUCCEEDED`), a new `ResaleAuthorization` is generated. Although the `SUCCEEDED` status indicates that the `CreateResaleAuthorization` change type call is completed, the `ResaleAuthorization` status is still in `Draft` state.
The following shows the response from the [DescribeChangeSet](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html) API operation.
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef",
"ChangeSetName": "Submitted by 123456789012",
"StartTime": "2021-05-27T22:21:26Z",
"EndTime": "2021-05-27T22:32:19Z",
"Status": "SUCCEEDED",
"ChangeSet":
[
{
"ChangeType": "CreateResaleAuthorization",
"Entity":
{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument":
{
"ProductId": "prod-ad8EXAMPLE51",
"Name": "Test ResaleAuthorization",
"Description": "Worldwide ResaleAuthorization for Test Product",
"ResellerAccountId": "777788889999",
"BulkRequestId": "84977023-5093-4a66-8b24-ef2c5a2f8b1f"
},
"ErrorDetailList":
[]
}
]
}
```
**Synchronous Validations**
The schema validations are specific to `CreateResaleAuthorization` actions in the AWS Marketplace Catalog API. The validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| ProductId | Required Must not be null or empty Length must be between 1 and 50 characters | 422 |
| ProductId | User must be authorized to create ResaleAuthorization for the given product | 403 |
| ProductId | Must be an existing product in the catalog and not in Draft state Product should be supported to resell | 404 |
| Name | Required Must not be null or empty Length must be between 1 and 100 characters No special characters allowed | 422 |
| Description | Optional Length must be between 1 and 255 characters No special characters allowed | 422 |
| ResellerAccountId | Required Must not be empty AWS account IDs must be in valid format (12-digit number) | 422 |
| BulkRequestId | Optional Length must be between 1 and 50 characters Must be in UUID format | 422 |
| An unknown property | No additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `CreateResaleAuthorization ` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1RESELLER\$1ACCOUNT | Provide a valid reseller account. |
## Update buyer targeting
You can use the Catalog API to update buyers targeting your Resale Authorization in AWS Marketplace.
Any existing targeting options that aren't included in the latest request are removed from the Resale Authorization. This change type is optional for release of the Resale Authorization.
To update buyers targeting your Resale Authorization, call the `StartChangeSet` API operation with the `UpdateBuyerTargetingTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType":"UpdateBuyerTargetingTerms",
"Entity":{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument":
{
"Terms":
[
{
"Type": "BuyerTargetingTerm",
"PositiveTargeting":
{
"BuyerAccounts":
[
"123456789012"
]
}
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateBuyerTargetingTerms` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request.
+ **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:
+ **BuyerTargetingTerms** (object) (optional) – Define buyer-specific targeting to your ResaleAuthorization.
+ **Type** (string) (required) – Category of the term being updated.
+ **PositiveTargeting** (object) (required) – Defines the criteria that any buyer’s profile should fulfill to be allowed access to the `ResaleAuthorization`.
+ **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.
**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 with the AWS Marketplace Seller Operations team to ensure 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 schema validations are specific to `UpdateBuyerTargetingTerms` 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 will fail with an HTTP response.
| 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) |
| BuyerTargetingTerm.PositiveTargeting | Required Must not be empty |
| BuyerTargetingTerm.PositiveTargeting.BuyerAccounts | Optional AWS account IDs must be in valid format (12-digit number) Must not contain more than 25 accounts |
| An unknown property | No additional properties are allowed |
**Asynchronous Errors**
The following errors are specific to `UpdateBuyerTargetingTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1BUYER\$1TARGETING | At least one Buyer account must be present for ResaleAuthorization with PreExistingBuyerAgreement. |
## Update availability
You can use the Catalog API to limit the availability of how many private offers are created or until what specific time a private offer can be created.
By default, the value is unlimited usage of this Resale Authorization, although you can check the availability under the rule list.
To control the availability and usability of your Resale Authorization, call the `StartChangeSet` API operation with the `UpdateAvailability` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateAvailability",
"Entity":
{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument":
{
"AvailabilityEndDate": "2022-05-31",
"OffersMaxQuantity": 1
}
}
]
}
```
Provide information for the fields to add the `UpdateAvailability` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request.
+ **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\$18601 format.
+ **OffersMaxQuantity** (integer) (optional) – Define the maximum number of private offers that can be created using the ResaleAuthorization. This doesn’t define the number of subscriptions.
**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 with the AWS Marketplace Seller Operations team to ensure 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 schema validations are specific to `UpdateAvailability` actions in the AWS Marketplace Catalog API. The validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response
| Input field | Validation rule |
| --- | --- |
| OffersMaxQuantity | Optional Must be non-negative integer Allowed value only "1" (Currently no use case to support multiple quantity) |
| AvailabilityEndDate | Optional Must be ISO\$18601 formatted Must be date in the future |
| Availability | Provide either OffersMaxQuantity or AvailabilityEndDate. |
| An unknown property | No additional properties are allowed |
**Asynchronous Errors**
The following errors are specific to `UpdateAvailability` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1AVAILABILITY\$1END\$1DATE | Provide an AvailabilityEndDate that is before all the ChargeDate in ResalePaymentScheduleTerms. |
| INVALID\$1AVAILABILITY\$1END\$1DATE | Provide a future AvailabilityEndDate. |
## Update the validity of a future dated agreement
You can use the Catalog API to modify and control a future dated service start date in AWS Marketplace.
This change set is not mandatory to release a Resale Authorization.
To modify and control the product agreement duration of your Resale Authorization, call the `StartChangeSet` API operation with the `UpdateBuyerValidityTerms` change type, as shown in the following example.
**Note**
Future-dated agreements are only supported for SaaS product types.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateBuyerValidityTerms",
"Entity":
{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument":
{
"Terms":
[
{
"Type": "BuyerValidityTerm",
"MaximumAgreementStartDate": "2024-05-31"
}
]
}
}
]
}
```
Provide information for the input fields to add the `UpdateBuyerValidityTerms` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request.
+ **Terms** (array of structures) – List of agreement validity terms that you want to update. Supported terms are:
+ **BuyerValidityTerm** (object) – Defines the availabilities of a service for a product in your ResaleAuthorization.
+ **Type** (string) – Category of term being updated.
+ **MaximumAgreementStartDate** (string) (required) – Define the agreement start date for the product offered. Future dated offers can’t exceed this service start date. Dates are represented in ISO\$18601 format.
**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 with the AWS Marketplace Seller Operations team to ensure 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 schema validations are specific to `UpdateBuyerValidityTerms` actions in the AWS Marketplace Catalog API. The validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| 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) |
| MaximumAgreementStartDate | Required Must not be null or empty Must be future date and shouldn't exceed more than 3 years from now Must be ISO\$18601 formatted |
| An unknown property | No additional properties are allowed |
**Asynchronous Errors**
The following errors are specific to `UpdateBuyerValidityTerms ` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PRODUCT | BuyerValidityTerm isn't supported for the product. |
| INVALID\$1MAXIMUM\$1AGREEMENT\$1START\$1DATE | Provide a future MaximumAgreementStartDate with in allowed limit. |
## Update legal resources
You can use the Catalog API to replace the existing legal terms completely in AWS Marketplace.
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.
To update legal terms of your `ResaleAuthorization`, call the `StartChangeSet` API operation with the `UpdateLegalTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdateLegalTerms",
"Entity":
{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument":
{
"Terms":
[
{
"Type": "BuyerLegalTerm",
"Documents":
[
{
"Type": "CustomEula",
"Url": "https://my-public-bucket.s3.amazonaws.com/eula-example12345.txt"
}
]
},
{
"Type": "ResaleLegalTerm",
"Documents":
[
{
"Type": "CustomResellerContract",
"Url": "https://my-public-bucket.s3.amazonaws.com/reseller-example12345.txt"
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateLegalTerms` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request.
+ **Terms** (array of structures) (required) – List of legal terms. Supported legal terms are:
+ **BuyerLegalTerm** (object) (required) – Defines the list of text agreements to be proposed to acceptors. For example, the end user license agreement (EULA).
+ **Type** (string) (required) – Category of the term being updated.
+ **Documents** (array of structures) (required) – List of references to legal resources to be proposed to the buyers. For example, the EULA. Each reference is made up of a `Type` and a `URL`:
+ **Type** (string) (required) – Type of document. Available document types are:
+ **StandardEula** – Standard Contract for AWS Marketplace. For more information, see [SCMP](https://docs.aws.amazon.com/marketplace/latest/userguide/standardized-license-terms.html#standard-contracts) in the *AWS Marketplace Seller Guide*. You don’t need to provide a URL for this type because it’s managed by AWS Marketplace.
+ **EnterpriseEula** – Enterprise Contract for AWS Marketplace. For more information, see DSA in the AWS Marketplace Seller Guide. You don’t need to provide a URL for this type because it’s managed by AWS Marketplace.
+ **CustomEula** – Custom EULA provided by you as a manufacturer. A URL for the EULA stored in an accessible S3 bucket is required for this document type.
+ **Url** (string) (conditionally required) – A URL to the legal document for buyers to read. This is required when category Type is `CustomEula`.
+ **ResaleLegalTerm** (object) (optional) – Defines the list of text agreements to propose only to channel partners. This term won’t be available to buyers.
+ **Type** (string) (required) – Category of term being updated.
+ **Documents** (array of structures) (required) – List of references to the reseller legal resources to be proposed to the channel partners.
+ **Type** (string) (required) – Category of the document. Available document types are:
+ **StandardResellerContract** – Standard Reseller Contract for AWS Marketplace.
+ **CustomResellerContract** – A custom reseller contract by you as a manufacturer. A URL for the reseller contract is stored in an accessible S3 bucket and is required for this document type.
+ **Url** (string) (conditionally required) – URL to the reseller contract document for channel partners to read. It’s required when the Type is CustomResellerContract.
**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 schema validations are specific to `UpdateLegalTerms` actions in the AWS Marketplace Catalog API. The validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Terms | Required Must not be null or empty | 422 |
| Terms[].BuyerLegalTerm | Required Must not be null or empty | 422 |
| Terms[].ResaleLegalTerm | Optional Must not be null or empty if present | 422 |
| Terms[].BuyerLegalTerm.Documents | Required Must not be null or empty | 422 |
| Terms[].BuyerLegalTerm.Documents[].Type | Required Must not be null or empty Allowed values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-resale-authorizations.html) | 422 |
| Terms[].BuyerLegalTerm.Documents[].Url | Required and must be a valid URL when "Type" is "CustomEula" Must not be provided when "Type" is one of ["StandardEula", "EnterpriseEula"] | 422 |
| Terms[].ResaleLegalTerm.Documents | Required Must not be null or empty | 422 |
| Terms[].ResaleLegalTerm.Documents[].Type | Required Must not be null or empty Allowed values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-resale-authorizations.html) | 422 |
| Terms[].ResaleLegalTerm.Documents[].Url | Required and must be a valid URL when "Type" is "CustomResellerContract" Must not be provided when "Type" is one of ["StandardContract"] | 422 |
| An unknown property | No additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateLegalTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet`, after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1BUYER\$1LEGAL\$1DOCUMENTS | Provide URLs for buyer legal documents stored in accessible S3 buckets. |
| INVALID\$1RESALE\$1LEGAL\$1DOCUMENTS | Provide URLs for resale legal documents stored in accessible S3 buckets. |
| MISSING\$1MANDATORY\$1TERMS | Provide a BuyerLegalTerm. |
## Update pricing
You can use the Catalog API to replace the existing pricing terms completely in AWS Marketplace.
Pricing terms that aren't included in the latest request will be removed from the Resale Authorization. You can update the discounted pricing for your product through this API.
To update pricing details for your Resale Authorizations, call the `StartChangeSet` API operation with the `UpdatePricingTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdatePricingTerms",
"Entity":
{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument":
{
"PricingModel": "Contract",
"Terms":
[
{
"Type": "ResaleUsageBasedPricingTerm",
"CurrencyCode": "USD",
"RateCards":
[
{
"RateCard":
[
{
"DimensionKey": "m3.large",
"Price": "0.10"
},
{
"DimensionKey": "m4.xlarge",
"Price": "0.20"
}
]
}
]
},
{
"Type": "ResaleConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards":
[
{
"Selector":
{
"Type": "Duration",
"Value": "P12M"
},
"RateCard":
[
{
"DimensionKey": "m3.large",
"Price": "300"
},
{
"DimensionKey": "m4.xlarge",
"Price": "400"
}
],
"Constraints":
{
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
},
{
"Type": "ResaleFixedUpfrontPricingTerm",
"CurrencyCode": "USD",
"Duration": "P2M",
"Price": "200.0",
"Grants":
[
{
"DimensionKey": "Users",
"MaxQuantity": 10
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdatePricingTerms` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request.
+ **PricingModel** (string) (required) – Pricing model for your offer. Possible values for pricing model are:
+ **Usage** – Usage-based pricing model where buyers will be billed for their usage of your product.
+ **Contract** – In the contract-based pricing model, buyers are either billed in advance for the use of your product or offered a flexible payment schedule. Buyers can also pay for additional usage above their contract. Channel partners can add their markup to this payment schedule and pricing for each dimension.
+ **Terms** (array of structures) (required) – List of pricing terms that you want to update. Supported pricing terms are:
+ **ResaleUsageBasedPricingTerm** (object) – Defines a pay-as-you-go (PAYG) pricing model where the customers are charged based on product usage.
+ **Type** (string) (required) – Category of the term.
+ **CurrencyCode** (string) – Defines the currency for prices mentioned in this term. Currently, only USD is supported.
+ **RateCards** (array of structures) – List of rate cards.
+ **RateCard** (array of structures) – A rate card defines the per-unit rates for the product dimensions.
+ **DimensionKey** (string) – 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.
+ **Price** (string) – Per unit price for the product dimension which is used for calculating the amount to be charged.
+ **Constraints** (object) (optional) – Defines limits on how the term can be configured by acceptors.
+ **MultipleDimensionSelection** (string) (optional) – Determines if buyers are allowed to select multiple dimensions in the rate card. Possible values are `Allowed` and `Disallowed`. Default value is `Allowed`.
+ **QuantityConfiguration** (string) (optional) – Determines if acceptors are allowed to configure quantity for each dimension in rate card. Possible values are `Allowed` and `Disallowed`. Default value is `Allowed`.
+ **ResaleFixedUpfrontPricingTerm** (object) – Defines a pre-paid pricing model where the customers are charged a fixed upfront amount.
+ **Type** (string) (required) – Category of the term being updated.
+ **CurrencyCode** (string) – Defines the currency for prices mentioned in this term. Defines the currency for the prices mentioned in this term. USD, AUD, EUR, GBP, and JPY are supported.
+ **Price** (string) (required) – Fixed amount to be charged to the customer when this term is accepted.
+ **Duration** (string) (required) – Contract duration of the ResaleAuthorization. This field supports the ISO 8601 format.
+ **Grants** (array of structures) (required) – Entitlements that will be granted to the acceptor of fixed upfront pricing as part of agreement execution.
+ **DimensionKey** (string) (required) – Unique dimension key defined in the product document. Dimensions represent categories of capacity in a product and are specified when the product is listed in AWS Marketplace.
+ **MaxQuantity** (integer) (required) – Maximum amount of capacity that the buyer can be entitled to the given dimension of the product. If MaxQuantity is not provided, the buyer will be able to use an unlimited amount of the given dimension.
**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 `UpdatePricingTerms` actions in the AWS Marketplace Catalog API. The validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule |
| --- | --- |
| Terms | Required Must not be null or empty Each term must present only single time Allowed terms: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-resale-authorizations.html) |
| Terms[].ResaleUsageBasedPricingTerm.CurrencyCode | Required Allowed values: USD |
| Terms[].ResaleUsageBasedPricingTerm.Validity | Required Must not be null or empty Expected format: ISO 8601 duration |
| Terms[].ResaleUsageBasedPricingTerm.RateCards | Required Must not be null or empty |
| Terms[].ResaleUsageBasedPricingTerm.RateCards[].DimensionKey | Required Must not be null or empty Length must be between 1 and 60 |
| Terms[].ResaleUsageBasedPricingTerm.RateCards[].Price | Required Must not be null or empty Data type is "String" Must be non-negative Support up to 8 Decimal No special characters supported |
| Terms[].ResaleConfigurableUpfrontPricingTerm.CurrencyCode | Required Allowed values: ["USD", "AUD", "EUR", "GBP", "JPN"] |
| Terms[].ResaleConfigurableUpfrontPricingTerm.RateCards[].Selector.Type | Required Must not be null or empty Allowed values: Duration |
| Terms[].ResaleConfigurableUpfrontPricingTerm.RateCards[].Selector.Value | Required Must not be null or empty Expected format: ISO 8601 duration |
| Terms[].ResaleConfigurableUpfrontPricingTerm.RateCards[].RateCard.DimensionKey | Required Must not be null or empty Length must be between 1 and 60 |
| Terms[].ResaleConfigurableUpfrontPricingTerm.RateCards[].RateCard.Price | Required Must not be null or empty Data type is "String" Must be non-negative Support up to 6 Decimal No special characters supported |
| Terms[].ResaleConfigurableUpfrontPricingTerm.RateCards[].Constraints | Optional |
| Terms[].ResaleFixedUpfrontPricingTerm.CurrencyCode | Required Allowed values: ["USD", "AUD", "EUR", "GBP", "JPN"] |
| Terms[].ResaleFixedUpfrontPricingTerm.Price | Required Must not be null or empty Data type is "String" Must be non-negative Support up to 6 Decimal No special characters supported Allowed values: 0.0 |
| Terms[].ResaleFixedUpfrontPricingTerm.Duration | Required Must not be null or empty Expected format: ISO 8601 duration |
| Terms[].ResaleFixedUpfrontPricingTerm.Grants[].DimensionKey | Required Must not be null or empty Length must be between 1 and 60 |
| Terms[].ResaleFixedUpfrontPricingTerm.Grants[].MaxQuantty | Required Must not be null or empty |
| An unknown property | No additional properties are allowed |
**Asynchronous Errors**
The following errors are specific to `UpdatePricingTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| INCOMPATIBLE\$1PRODUCT | Use existing, available dimensions in the product in [x]. |
| DUPLICATE\$1DIMENSION\$1KEYS | Provide rate card with a unique list of dimension keys in [x] |
| INVALID\$1RATE\$1CARD | Provide dimensions that have the same unit in [x] |
| INVALID\$1RATE\$1CARD | Provide a rate card for only metered dimensions in ResaleUsageBasedPricingTerm. |
| INVALID\$1RATE\$1CARD | Provide usage based rates for all available metered dimensions in ResaleUsageBasedPricingTerm. |
| TOO\$1MANY\$1RATES | Provide RateCards within the allowed limits in ResaleUsageBasedPricingTerm. |
| DUPLICATE\$1SELECTORS | Provide a unique list of Selectors in ResaleConfigurableUpfrontPricingTerm. |
| INVALID\$1RATE\$1CARD | ConfigurableUpfrontPricingTerm is missing one or more dimension keys for duration [x]. Provide prices for the same set of dimension keys for all durations. |
| INVALID\$1RATE\$1CARD | Provide either all metered or all entitled dimensions in [x]. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | Set MultipleDimensionSelection and QuantityConfiguration to Disallowed in ResaleConfigurableUpfrontPricingTerm for the PricingModel. |
| TOO\$1MANY\$1RATE\$1CARDS | Only one rate card in ConfigurableUpfrontPricingTerm is allowed for the product. |
| INCOMPATIBLE\$1TERMS | The following terms aren't compatible with the PricingModel: [x,y,z]. |
| TOO\$1MANY\$1RATES | Provide RateCards within the allowed limits in [x term]. |
| TOO\$1MANY\$1GRANTS | Provide up to [N] grants in [x term]. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide duration between [x] and [y] months in ResaleConfigurableUpfront |
| TOO\$1MANY\$1GRANTS | Provide duration between [x] and [y] months. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Ensure duration granularity is at the day level for metered dimensions in ResaleConfigurableUpfront |
| INVALID\$1DURATION | Ensure duration granularity is at the day level for metered dimensions in FixedUpfront. |
| INVALID\$1RATE\$1CARD | Provide only entitled dimensions in [x]. |
| MISSING\$1DURATION | Provide a Duration in [x]. |
| DUPLICATE\$1DIMENSION\$1KEYS | Provide Grants with a unique list of dimension keys in [x]. |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INVALID\$1CURRENCY\$1CODE | Provide a supported CurrencyCode. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| INCOMPATIBLE\$1CURRENCY\$1CODE | CurrencyCode can't be changed after the offer is released. |
## Update payment schedule
You can use the Catalog API to change payment-associated details, such as a flexible payment schedule, in AWS Marketplace.
To update payment-associated details for your Resale Authorization, call the `StartChangeSet` API operation with the `UpdatePaymentScheduleTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "UpdatePaymentScheduleTerms",
"Entity":
{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument":
{
"Terms":
[
{
"Type": "ResalePaymentScheduleTerm",
"CurrencyCode": "USD",
"Schedule":
[
{
"ChargeDate": "2021-12-01",
"ChargeAmount": "200.00"
},
{
"ChargeDate": "2022-03-01",
"ChargeAmount": "250.00"
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdatePaymentScheduleTerms` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request.
+ **Terms** (array of structures) – List of payment terms that you want to update. Supported payment terms are:
+ **ResalePaymentScheduleTerm** (object) – Defines an installment-based pricing model where the customers are charged a fixed price on different dates during the agreement validity period.
+ **Type** (string) – Category of the term being updated.
+ **CurrencyCode** (string) (required) – Defines the currency for the payment mentioned in the schedule. USD, AUD, EUR, GBP, and JPY are supported.
+ **Schedule** (array of structures) – List of the payment schedule where each element defines one installment of payment. It contains the information necessary for calculating the price to be paid and the date on which the customer would be charged.
+ **ChargeDate** (string) (required) – The date the customer would pay the price defined in this payment schedule term. This field supports the ISO 8601 format.
+ **ChargeAmount** (string) (required) – The price the customer would pay on a scheduled date (ChargeDate).
**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 schema validations are specific to `UpdatePaymentScheduleTerms` actions in the AWS Marketplace Catalog API. The validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP |
| --- | --- | --- |
| Terms.Type | Required Not supported for [x] product Allowed terms: ResalePaymentScheduleTerm | 422 |
| Terms[].CurrencyCode | Required Allowed values: USD | 422 |
| Terms[].ResalePaymentScheduleTerm.Schedule | Required Length must be between 1 and 60 | 422 |
| Terms[].ResalePaymentScheduleTerm.Shedule.ChargeDate | Required Must be in ISO 8601 format Date must be in the future | 422 |
| Terms[].ResalePaymentScheduleTerm.Shedule.ChargeAmount | Required Must be non-negative | 422 |
| An unknown property | No additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdatePaymentScheduleTerms` 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.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1TERMS | OffersMaxQuantity and AvailabilityEndDate must be present with ResalePaymentScheduleTerm. |
| TOO\$1MANY\$1SCHEDULED\$1PAYMENTS | Provide up to 60 scheduled payments in ResalePaymentScheduleTerm. |
| DUPLICATE\$1CHARGE\$1DATES | Provide unique charge dates in ResalePaymentScheduleTerm. |
| INVALID\$1CHARGE\$1DATES | Provide a future ChargeDate. |
| INVALID\$1CHARGE\$1DATES | Provide a last charge date that is before [x]. |
| MISSING\$1MANDATORY\$1TERMS | Provide a ResaleFixedUpfrontPricingTerm and ResalePaymentScheduleTerm together. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INVALID\$1CURRENCY\$1CODE | Provide a supported CurrencyCode. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| INCOMPATIBLE\$1CURRENCY\$1CODE | CurrencyCode can't be changed after the offer is released. |
## 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": "ResaleAuthorization@1.0",
"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 `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#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 channel partners.
+ **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 Pattern ^[A-Za-z0-9]\$1\$1 No special character or white space allowed | 422 |
| Description | Optional Length must be between 1 and 255 characters Pattern ^[A-Za-z0-9\$1\$1s]\$1\$1 No special characters allowed | 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.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1BUYER\$1TARGETING | At least one Buyer account must be present for ResaleAuthorization with PreExistingBuyerAgreement. |
## Restrict a Resale Authorization
You can use the Catalog API to set restrict rules to a Resale Authorization in AWS Marketplace.
A restricted Resale Authorization can no longer be used by a channel partner to create a private offer. An existing private offer won’t be impacted.
To restrict your Resale Authorization, call the `StartChangeSet` API operation with the `RestrictResaleAuthorization` change type, as shown in the following example.
**Important**
This is a non-reversible operation. After the Resale Authorization is marked as `Restricted`, it can’t be in an `Active` state again.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "RestrictResaleAuthorization",
"Entity": {
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument": {}
}
]
}
```
Provide information for the fields to add the `RestrictResaleAuthorization` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request. It must be an empty object for `RestrictResaleAuthorization`.
**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 schema validations are specific to `RestrictResaleAuthorization` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| DetailsDocument | Must be empty | 422 |
| RestrictResaleAuthorization | Expired ResaleAuthorization can't be marked as `Restricted` | 422 |
| An unknown property | No additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `RestrictResaleAuthorization` 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.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1STATUS | Expired ResaleAuthorization can't be marked as restricted. |
## Release a Resale Authorization and make it visible to a Channel Partner
You can use the Catalog API to initiate your `ResaleAuthorization` to an `Active` state.
`ReleaseResaleAuthorization` makes your Resale Authorization active so that a Channel Partner can use your Resale Authorization to create private offers.
To release your Resale Authorization, call the `StartChangeSet` API operation with the `ReleaseResaleAuthorization` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet":
[
{
"ChangeType": "ReleaseResaleAuthorization",
"Entity":
{
"Type": "ResaleAuthorization@1.0",
"Identifier": "resaleauthz-123456789"
},
"DetailsDocument": {}
}
]
}
```
Provide information for the fields to add the `ReleaseResaleAuthorization` change type:
+ **Entity** (object) (required) – Your Resale Authorization.
+ **Type** (string) (required) – The `Type` is always `ResaleAuthorization@1.0`.
+ **Identifier** (string) (required) – Your Resale Authorization ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – Specifics of the request. It must be empty for `ReleaseResaleAuthorization`.
**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 schema validations are specific to `ReleaseResaleAuthorization` actions in the AWS Marketplace Catalog API. The validations are performed when you call `StartChangeSet`. If the request doesn’t meet the following requirements, it will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| An unknown property | No additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `ReleaseResaleAuthorization` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more details about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| MISSING\$1MANDATORY\$1TERMS | Provide a BuyerLegalTerm. |
| MISSING\$1MANDATORY\$1TERMS | Provide a PricingTerm. |
| INCOMPATIBLE\$1PRODUCT | Use an active product in limited or public state. |
| INCOMPATIBLE\$1PRICING\$1TERM | PaymentScheduleTerm and FixedUpfrontPricingTerm must be present together. |
| INCOMPATIBLE\$1BUYER\$1TARGETING | At least one Buyer account must be present for ResaleAuthorization with PreExistingBuyerAgreement. |
| MISSING\$1MANDATORY\$1TERMS | Provide at least one of [x,y,z]. |
| INCOMPATIBLE\$1STATUS | [x] request can't be performed after the resale authorization is released. |
## Describe an existing Resale Authorization
To describe Resale Authorization details, call the `DescribeEntity` API operation with the `ResaleAuthorization@1.0` entity type, as shown in the following example.
**Request Syntax**
```
GET /DescribeEntity?catalog=&entityId= HTTP/1.1
```
Provide information for the fields to add the `DescribeEntity` change type:
+ **catalog** (string) – The catalog related to the request. Fixed value: `AWSMarketplace`.
+ **entityId** (string) – The unique ID of the `ResaleAuthorization` to describe.
**Response Syntax**
The response to this request gives you the offer details and looks like the following.
```
{
"EntityType": "ResaleAuthorization@1.0",
"EntityIdentifier": "resaleauthz-123456789",
"EntityArn": "arn:aws:aws-marketplace:us-east-1:111122223333:AWSMarketplace/ResaleAuthorization/resaleauthz-123456789",
"LastModifiedDate": "2021-03-10T21:57:16Z",
"DetailsDocument": {
"Name": "TestResaleAuthorization",
"Description": "ResaleAuthorization for Test Product",
"ProductId": "prod-ad8EXAMPLE51",
"ProductName": "TestProduct",
"Status": "Active", /*Draft, Active, Restricted*/
"PreExistingBuyerAgreement": {
"AcquisitionChannel": "Unknown",
"PricingModel": "Unknown"
},
"CreatedDate": "2023-07-18T16:39:31.335Z",
"ManufacturerLegalName": "ChannelCAPI.Inc",
"ManufacturerAccountId": "123456789012",
"Dimensions": [
{
"Name": "Protected Resources",
"Description": "Additional 100 protected resources",
"Key": "hundredresources",
"Unit": "Units",
"Types": [
"Entitled"
]
}
],
"OfferDetails": {
"OfferExtendedStatus": "Not Started", /* Not Started, Completed-Used, Completed-Usable*/
"OfferCreatedCount": 0
},
"Terms": [
{
"Type": "ResaleUsageBasedPricingTerm",
"Id": "term_id_placeholder",
"CurrencyCode": "USD",
"RateCards": [
{
"RateCard": [
{
"DimensionKey": "resource_number",
"Price": "0.05"
},
{
"DimensionKey": "scanned_data",
"Price": "0.05"
}
]
}
]
},
{
"Type": "ResaleConfigurableUpfrontPricingTerm",
"Id": "term_id_placeholder",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P24M"
},
"RateCard": [
{
"DimensionKey": "hundredresources",
"Price": "0.04"
},
{
"DimensionKey": "tenTBData",
"Price": "0.03"
},
{
"DimensionKey": "channel_custom",
"Price": "0.02"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
},
{
"Type": "ResaleFixedUpfrontPricingTerm",
"Id": "term-sdh27fb2",
"CurrencyCode": "USD",
"Duration": "P180D",
"Price": "0.0",
"Grants": [
{
"DimensionKey": "sdf73rbns93nl120d10xm1",
"MaxQuantity": 1
}
]
},
{
"Type": "ResalePaymentScheduleTerm",
"Id": "term-sdh27fb2",
"CurrencyCode": "USD",
"Schedule": [
{
"ChargeDate": "2018-07-01T00:00:00.000Z",
"ChargeAmount": "200.00"
},
{
"ChargeDate": "2019-05-01T00:00:00.000Z",
"ChargeAmount": "200.00"
}
]
},
{
"Type": "BuyerLegalTerm",
"Id": "term_id_placeholder",
"Documents": [
{
"Type": "StandardEula",
"Url": "https://resale-auth-legal-terms-iad-beta.s3.us-east-1.amazonaws.com/09ae57d6-c75a-3a4c-aadf-9b866bae64ab/a85cace8-6d9d-40ca-a053-78fc265479bf?isSigned=yes"
}
]
},
{
"Type": "ResaleLegalTerm",
"Id": "term_id_placeholder",
"Documents": [
{
"Type": "StandardResellerContract",
"Url": "https://resale-auth-legal-terms-iad-beta.s3.us-east-1.amazonaws.com/09ae57d6-c75a-3a4c-aadf-9b866bae64ab/bed55b56-7ab4-4c4c-b633-3bf4f6efcb98?isSigned=yes"
}
]
},
{
"Type": "BuyerValidityTerm",
"Id": "term_id_placeholder",
"MaximumAgreementStartDate": "2023-09-25T23:59:59.000Z"
},
{
"Type": "BuyerTargetingTerm",
"Id": "term_id_placeholder",
"PositiveTargeting": {
"BuyerAccounts": [
{
"AwsAccountId": "444455556666"
}
]
}
}
],
"Rules": [
{
"Type": "AvailabilityRule",
"Id": "availability_rule_id_placeholder",
/* If the AvailabilityEndDate and OffersMaxQuantity not present Usage will be Unlimited*/
"Usage": "Limited",
"AvailabilityEndDate": "2022-05-31T23:59:59Z",
"OffersMaxQuantity": 1
},
{
"Type": "PartnerTargetingRule",
"Id": "partner_targeting_rule_id_placeholder",
"ResellerAccountId": "777777777777",
"ResellerLegalName": "ChannelCAPICP.Inc"
}
]
}
}
```
The following is information about the fields you see in the `DescribeEntity` response.
+ **EntityType** (string) – The named type of the entity, which is ResaleAuthorization@1.0.
+ **EntityIdentifier** (string) – The identifier of the entity, in the format of EntityId@RevisionId.
+ **EntityArn** (string) – The ARN associated to the unique identifier for the change set referenced in this request.
+ **LastModifiedDate** (string) – The last modified date of the entity, in ISO 8601 format (2018-02-27T13:45:22Z).
+ **DetailsDocument** (object) (required) – This JSON string includes the details of the entity.
+ **Name** (string) – Name associated with the ResaleAuthorization for better readability to you and your Channel Partners. It’s displayed as part of the Agreement information.
+ **Description** (string) – Description is a free-form text which is meant to be used only by you and will never be exposed to buyers.
+ **ProductId** (string) – Description is a free-form text which is meant to be used only by you and will never be exposed to buyers.
+ **AgreementToken** (string) – Generated from content in ResaleAuthorization. It contains information about terms, rules, and proposer while creating an agreement. It's used for authorization checks and validations during procurement.
+ **Terms** (array of structures) – List of terms presented for acceptance.
+ **Rules** (array of structures) – List of rules or set of instructions.
# Work with channel partner private offers using the AWS Marketplace APIs
You can use the AWS Marketplace Catalog API to automate tasks for working with channel partner private offers (CPPOs).
When you create or update a CPPO, the draft offer will contain the terms and rules from a Resale Authorization and will be invisible to the buyer. It’s possible, but not required, to involve multiple personas in your organization to create a private offer.
For example, one persona can be responsible for updating prices while a second persona can be responsible for updating the payment schedule. Then, a third persona can be responsible for updating legal terms. You can give a persona permission to update certain parts of an offer. However, you can give only read permissions to Resale Authorizations.
As a prerequisite for calling change types, you must have received one or more Resale Authorizations and be familiar working with AWS Marketplace Catalog API.
For more information, see [ Channel partner private offers](https://docs.aws.amazon.com/marketplace/latest/userguide/channel-partner-offers.html) in the *AWS Marketplace Seller Guide*.
The following topics describe how to use the Catalog API to create and update CPPOs:
**Topics**
+ [
## CPPO prerequisites
](#cppo-prerequisites)
+ [
## Create a CPPO
](#create-offer-using-resale-auth)
+ [
## Create a channel partner private replacement offer
](#create-replacement-offer-using-resale-auth)
+ [
## Update markup
](#update-markup)
+ [
## Update targeting configuration
](#update-targeting-cppo)
+ [
## Update legal resources
](#update-legal-terms-cppo)
+ [
## Update the discoverability of the CPPO
](#update-availability-cppo)
+ [
## Define the expiration date of agreements
](#update-validity-terms-cppo)
+ [
## Update pricing
](#update-pricing-terms-cppo)
+ [
## Update payment schedule details
](#update-payment-schedule-terms-cppo)
+ [
## Publish the CPPO
](#release-offer-cppo)
+ [
## Define an existing CPPO
](#describe-entity-cppo)
## CPPO prerequisites
Service-linked role for ResaleAuthorization (SLR) setup is a mandatory pre-requisite to use resale authorization to create a CPPO. 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*.
## Create a CPPO
You use a Resale Authorization targeted to you to create a channel partner private offer (CPPO) in `Draft` state in AWS Marketplace.
If your request is processed successfully, AWS Marketplace Catalog API generates an offer in `Draft` state for you with Resale Authorization terms. You can use `DescribeEntity` to see the terms applied to the draft offer from Resale Authorization. This is an incomplete offer and not visible to buyers in AWS Marketplace. You then use change types associated with the CPPO to complete the offer.
After the offer is completed, you use the `ReleaseOffer` change type to complete the offer creation process and release the offer. This will validate the entire offer and make your offer visible to buyers in AWS Marketplace.
To create a channel partner private offer, call the `StartChangeSet` API operation with the `CreateOfferUsingResaleAuthorization` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "CreateOfferUsingResaleAuthorization",
"Entity": {
"Type": "Offer@1.0"
},
"DetailsDocument": {
"ResaleAuthorizationId": "resaleauthz-123456789",
"Name": "Test Offer",
"OfferSetId": "offerset-b3f9EXAMPLE27"
}
}
]
}
```
Provide information for the fields to add the `CreateOfferUsingResaleAuthorization` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **ResaleAuthorizationId** (string) (required) – The unique identifier that includes product, terms, and rules that are being offered. Channel partners can add additional terms and rules using update change types. ResaleAuthorization must be available and targeted to you as a partner.
+ **Name** (string) (optional) – The name associated with the offer for better readability. It is displayed as a part of the agreement information.
+ **OfferSetId** (string) (optional) – The ID of the offer set to associate this offer with. Only specify this field when creating an offer that will be part of an offer set. If OfferSetId is not provided, an individual offer will be created that can be purchased standalone. Note that specifying an OfferSetId during offer creation only indicates your intent to associate the offer with that offer set. To complete the association, you must [use the AssociateOffers change type](work-with-offer-sets.md#associate-offers) after the offer is created.
**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.
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.
The response to this request gives you the status of the request. If the status is `SUCCEEDED`, then a new `OfferId` is generated.
```
{
"ChangeSetId": "example123456789012abcdef",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef",
"ChangeSetName": "Submitted by 123456789012",
"StartTime": "2021-05-27T22:21:26Z",
"EndTime": "2021-05-27T22:32:19Z",
"Status": "SUCCEEDED",
"ChangeSet": [
{
"ChangeType": "CreateOfferUsingResaleAuthorization",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"ResaleAuthorizationId": "resaleauthz-123456789",
"Name": "Test Offer"
},
"ErrorDetailList": []
}
]
}
```
You can use the `GET` `DescribeEntity` request to describe the draft offer rules and terms created from `ResaleAuthorization` in the AWS Marketplace Catalog API Reference. For more information, see [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_DescribeChangeSet.html).
**Terms and rules from ResaleAuthorization**
+ **LegalTerms** – Provisions describing legal terms, such as the EULA in the ResaleAuthorization will be added to the draft offer. You can add legal terms using the `UpdateLegalTerms` change type. For more information, see [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-legal-terms-cppo](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-legal-terms-cppo).
+ **PricingTerms** – All the pricing terms (`ConfigurableUpfrontPricingTerm`, `FixedUpfrontPricingTerm`, `UsageBasedPricingTerm`, `PaymentScheduleTerms`) described by the Manufacturer in the ResaleAuthorization will be added to the draft offer. You can choose to increase the pricing (for each dimension) for your targeted buyers using the `UpdateMarkup` change type. For more information, see [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-markup](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-markup) in this guide.
+ **PaymentTerms** – If the manufacturer has defined the Future Payment Schedule in the ResaleAuthorization, then you will be able to see the payment terms in the draft offer. You can choose to increase the payment schedule amount for your targeted buyers using the `UpdateMarkup` change type. If you want to set the payment schedule for your buyers, you can use `UpdatePaymentScheduleTerms`. For more information, see [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-payment-schedule-terms-cppo](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-payment-schedule-terms-cppo).
+ **TargetingRule** – If the ResaleAuthorization is targeted to specific buyers, then channel partners can give private offers to a subset of buyers using PositiveTargeting. By default, the rule will include all the buyers from ResaleAuthorization. You can select specific buyers and update the draft offer using the `UpdateTargeting` change type. For more information, see [https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-targeting-cppo](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/cppos.html#update-targeting-cppo).
```
{
"EntityType": "Offer@1.0",
"EntityIdentifier": "offer-a5EXAMPLEwzpu@1",
"EntityArn": "arn:aws:aws-marketplace:us-east-1:444555666777:AWSMarketplace/Offer/offer-a5oEXAMPLEzpu",
"LastModifiedDate": "2021-03-10T21:57:16Z",
"DetailsDocument": {
"Id": "offer-3rb23tu92rn",
"Name": "Test Offer",
"Description": "Worldwide private offer for Test Product",
"ProductId": "prod-0bc848d78b51",
"ResaleAuthorizationId": "resaleauthz-123456789",
"Terms": [
{
"Type": "LegalTerm",
"Documents": [
{
"Type": "CustomEula",
"Url": "https://s3.amazonaws.com/EULA/custom-eula-1234.txt"
}
]
},
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P12M"
},
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "300.00"
},
{
"DimensionKey": "m4.xlarge",
"Price": "400.00"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
},
{
"Type": "UsageBasedPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "0.10"
},
{
"DimensionKey": "m4.xlarge",
"Price": "0.20"
}
]
}
]
},
{
"Type": "PaymentScheduleTerm",
"CurrencyCode": "USD",
"Schedule": [
{
"ChargeDate": "2020-12-01T00:00:00.000Z",
"ChargeAmount": "1000.00"
},
{
"ChargeDate": "2021-06-15T00:00:00.000Z",
"ChargeAmount": "1250.00"
}
]
}
],
"Rules": [
{
"Type": "TargetingRule",
"PositiveTargeting": {
"BuyerAccounts": [
"111222333444"
]
}
}
]
}
}
```
**Synchronous Validations**
The following schema validations are specific to `CreateOfferUsingResaleAuthorization` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Name | Required Length must be between 1 and 150 characters | 422 |
| Description | Required Length must be between 1 and 255 characters | 422 |
| ResaleAuthorizationId | Required Length must be between 1 and 50 characters | 422 |
| ResaleAuthorizationId | ResaleAuthorization must be targeted to the channel partner. | 422 |
| ResaleAuthorizationId | ResaleAuthorization must be active | 422 |
| Channel Partner | Channel Partner must be paid seller in AWS Marketplace | 422 |
**Asynchronous Errors**
The following errors are specific to `CreateOfferUsingResaleAuthorization` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Use a ResaleAuthorization in active state. |
| INCOMPATIBLE\$1PRODUCT | OfferSetId isn't supported in offers for the product. |
## Create a channel partner private replacement offer
You can use the Catalog API to create a channel partner private replacement offer in AWS Marketplace.
You use the `ResaleAuthorization` targeted to you and an Agreement of which you are the proposer to create a channel partner private replacement offer in `Draft` state in the Catalog API by calling `StartChangeSet` with the `CreateReplacementOfferUsingResaleAuthorization` change type, as shown in the following example. Replacement offers can be used to replace an agreement from a previous offer before it ends.
`CreateReplacementOfferUsingResaleAuthorization` will create a draft offer with the agreement acceptor in targeting. This targeting cannot be changed afterwards. The draft offer will also contain the source offer id of the agreement.
To create a channel partner private replacement offer, call the `StartChangeSet` API operation with the `CreateReplacementOfferUsingResaleAuthorization` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "CreateReplacementOfferUsingResaleAuthorization",
"Entity": {
"Type": "Offer@1.0"
},
"DetailsDocument": {
"ResaleAuthorizationId": "2bd2c761-3b7f-3771-a9a7-e8ad36517698",
"Name": "CAPI-saas-abo-contract-fps",
"AgreementId": "agmt-f2ooEXAMLEamtm7mjj0j59gu"
}
}
]
}
```
Provide information for the fields to add the `CreateReplacementOfferUsingResaleAuthorization` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **ResaleAuthorizationId** (string) (required) – `ResaleAuthorizationId` is the unique identifier which includes product, terms and rules are being offered. Channel partners can add additional terms and rules using Update change types.
`ResaleAuthorization` must be available and targeted to you as a partner.
+ **Name** (string) (optional) – `Name` associated with the offer for better readability to you and your customers. It will be displayed as part of Agreement information as well.
+ **AgreementId** (string) (required) – `AgreementId` is the unique identifier of the agreement created when the targeted buyer accepted the previous offer you are trying to replace
**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.
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 `CreateReplacementOfferUsingResaleAuthorization` 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 will fail with an HTTP response.
| Input field | Validation rule |
| --- | --- |
| Name | Length must be between 1 and 150 characters |
| AgreementId | Provided agreement must be active Provided agreement must exist Provided agreement must be owned by Channel Partner |
| ResaleAuthorizationId | Required Length must be between 1 and 50 characters |
| ResaleAuthorizationId | ResaleAuthorization must be targeted to the channel partner. |
| ResaleAuthorizationId | ResaleAuthorization must be active |
| Channel Partner | Channel Partner must be paid seller in AWS Marketplace |
**Asynchronous Errors**
The following errors are specific to `CreateReplacementOfferUsingResaleAuthorization` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Use a ResaleAuthorization in active state. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | The ResaleAuthorization must be for the same product that is associated with the agreement. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Use a ResaleAuthorization targeted to the acceptor of the agreement. |
## Update markup
You can use the Catalog API to update pricing terms by a percentage value in your offer in AWS Marketplace.
This will apply the given percentage markup on all pricing terms and payment terms (for future payment schedules) that are defined by the manufacturer in the ResaleAuthorization. Any existing markup will be overwritten. You can view updated pricing and payment terms using `DescribeEntity`.
To update markup, call the `StartChangeSet` API operation with the `UpdateMarkup` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateMarkup",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Percentage": "5.0"
}
}
]
}
```
Provide information for the fields to add the `UpdateMarkup` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Percentage** (string) (required) – Percentage value will be added to the manufacturer pricing or payment terms.
**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 with the AWS Marketplace Seller Operations team to ensure 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 `UpdateMarkup` 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 will fail with an HTTP response.
| Input field | Validation rule |
| --- | --- |
| Percentage | Required Data type is "String" Must be non-negative Allow up to 9 decimals |
**Asynchronous Errors**
The following errors are specific to `UpdateMarkup` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1MARKUP | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | MarkupPercentage can't be updated when PaymentScheduleTerm or FixedUpfrontPricingTerm are present in offer and not present in ResaleAuthorization. |
| INCOMPATIBLE\$1TERMS | Use either UpdatePaymentScheduleTerms with specific payment amount or UpdateMarkup with a single markup percentage for the scheduled dates. |
| INVALID\$1MARKUP\$1PERCENTAGE | UpdateMarkup can only be invoked for offers created using ResaleAuthorization. |
## Update targeting configuration
You can use the Catalog API to replace the existing targeting configuration completely in AWS Marketplace.
Any existing targeting options that are not included in the latest request will be removed from the offer. Manufacturers can mention specific targeted buyers in `ResaleAuthorization`. Channel partners can give private offers to a subset of buyers using `PositiveTargeting` in the `UpdateTargeting` change type.
To update targeting configurations of your offer, call the `StartChangeSet` API operation with the `UpdateTargeting` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateTargeting",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"PositiveTargeting": {
"CountryCodes": [
"US",
"CA"
],
"BuyerAccounts": [
"111222333444"
]
},
"NegativeTargeting": {
"CountryCodes": [
"XX"
]
}
}
}
]
}
```
Provide information for the fields to add the `UpdateTargeting` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **PositiveTargeting** (object) (optional) – Positive targeting defines the criteria which any buyer's profile should fulfill in order to be allowed to access the offer. This field is optional, but at least one targeting option should be provided when this field is present.
+ **CountryCodes** (array of strings) (optional) – List as option for allowing targeting based on country. If the intention isn’t to target the offer to a country, this field should be omitted. If it’s present, the list must contain at least one country code. Each element in this list should be a valid 2-letter country code, using this format: ISO 3166-1 alpha-2.
+ **BuyerAccounts** (array of strings) (optional) – List as an option to allow targeting based on AWS accounts (also known as, Private Offer). If the intention is to not target the offer to an AWS account, this field should be omitted.
+ **NegativeTargeting** (object) (optional) – Negative targeting defines the criteria which any customer's profile should fulfill to be restricted to access the offer. Although this field is optional, at least one targeting option should be provided when this field is present.
+ **CountryCodes** (array of strings) (required) – List as option for allowing targeting based on country. If the intention isn’t to target the offer to a specific country, then this field should be omitted. If it’s present, the list must contain at least one country code. Each element in this list should be a valid 2-letter country code using this format: ISO 3166-1 alpha-2.
**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 `UpdateTargeting` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Details | Required | 422 |
| PositiveTargeting | Optional | 422 |
| NegativeTargeting | Optional | 422 |
| PositiveTargeting.CountryCodes | Optional Country codes must be valid (ISO 3166-1 alpha-2) | 422 |
| PositiveTargeting.BuyerAccounts | Optional AWS account IDs must be in valid format (12-digit number) Must not contain more than 25 accounts | 422 |
| NegativeTargeting.CountryCodes | Optional Country codes must be valid (ISO 3166-1 alpha-2) | 422 |
| NegativeTargeting.BuyerAccounts | Must not be provided (negative targeting on BuyerAccounts isn’t supported) | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateTargeting` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1BUYER\$1ACCOUNTS | Provide valid buyer accounts. Invalid accounts: [x]. |
| INVALID\$1COUNTRY\$1CODES | Provide supported country codes. |
| INVALID\$1TARGETING | Use either negative or positive targeting on the same attribute. |
| INCOMPATIBLE\$1PRODUCT | Country-based targeting isn't supported for the product. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide BuyerAccounts that are compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1TARGETING | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TARGETING | The requested change can't be performed after the offer is expired. |
| INCOMPATIBLE\$1TARGETING | Targeting can't be updated on a replacement offer. If the buyer isn't associated with the provided AgreementId, then create a new private offer by providing an AgreementId associated with the buyer. |
| TOO\$1MANY\$1BUYER\$1ACCOUNTS | Provide BuyerAccounts within the allowed limits. |
## Update legal resources
You can use the Catalog API to merge the Resale Authorization legal terms and replace the existing legal terms completely in AWS Marketplace.
This change doesn’t affect existing agreements. The legal terms that aren't included in the latest request will be removed from the offer. You can view the merged legal terms by calling `DescribeEntity`.
To update legal terms of your offer, call the `StartChangeSet` API operation with the `UpdateLegalTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateLegalTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "LegalTerm",
"Documents": [
{
"Type": "CustomEula",
"Url": "https://s3.amazonaws.com/EULA/custom-eula-1234.txt"
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateLegalTerms` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Terms** (array of structures) (required) – List of legal terms that you want to update. Supported legal terms are:
+ **LegalTerm** (object) (required) – Defines the list of text agreements to be proposed to the acceptors. One example of such an agreement is the end user license agreement (EULA).
+ **Type** (string) (required) – Category of term being updated.
+ **Documents** (array of structures) (required) – List of references to legal resources to be proposed to the buyers. One example of such a resource is the end user license agreement (EULA). Each reference is made up of a Type and a URL:
+ **Type** (string) (required) – Type of document. Available document types are:
+ **CustomEula** – A custom EULA provided by you as seller. A URL for a EULA stored in an accessible S3 bucket is required for this document type.
+ **StandardEula** – Standard Contract For AWS Marketplace (SCMP). For more information about SCMP, see the AWS Marketplace Seller Guide. You don’t provide a URL for this type because it is managed by AWS Marketplace.
+ **Url** (string) (conditionally required) – A URL to the legal document for buyers to read. Required when `Type` is one of the following [`CustomEula`].
+ **Version** (string) (conditionally required) – A version of standard contracts provided by AWS Marketplace. This is required when `Type` is `StandardEula`. Available versions are:
+ **2022-07-14** – This version of the Standard Contract for AWS Marketplace is available from this Amazon S3 bucket: [https://s3.amazonaws.com/aws-mp-standard-contracts/Standard-Contact-for-AWS-Marketplace-2022-07-14.pdf](https://s3.amazonaws.com/aws-mp-standard-contracts/Standard-Contact-for-AWS-Marketplace-2022-07-14.pdf)
A change set is created for your request. The response to this request gives you the ID for the change set.
**Response Syntax**
```
{
"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 with the AWS Marketplace Seller Operations team to ensure 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 in the Catalog API with the `DescribeChangeSet` action.
**Synchronous Validations**
The following schema validations are specific to `UpdateLegalTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Terms | Required Only LegalTerm is allowed in the list List size must be 1 | 422 |
| Terms[].LegalTerm.Documents | Required | 422 |
| Terms[].LegalTerm.Documents[].Type | Required Allowed values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-cppos.html) | 422 |
| Terms[].LegalTerm.Documents[].Url | Required and must be a valid URL when "Type" is one of [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-cppos.html) | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateLegalTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1LEGAL\$1DOCUMENTS | Provide URLs for legal documents stored in accessible S3 buckets. |
| INVALID\$1LEGAL\$1DOCUMENTS | Only the most recent version of StandardEula is supported for new offers. |
| INVALID\$1LEGAL\$1DOCUMENTS | Provide legal documents in the supported file formats. |
| INVALID\$1LEGAL\$1DOCUMENTS | Provide legal documents using the supported document types. |
| LIMIT\$1EXCEEDED\$1LEGAL\$1DOCUMENT\$1SIZE | Provide legal documents within the allowed size limits. |
## Update the discoverability of the CPPO
You can use the Catalog API to manage the discoverability of your offer in AWS Marketplace. This change type doesn’t affect existing agreements.
You can either choose to set a specific date in the future to restrict the discoverability of your offer or in the past to expire your offer.
To manage the discoverability of your offer, call the `StartChangeSet` API operation with the `UpdateAvailability` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateAvailability",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"AvailabilityEndDate": "2024-05-31"
}
}
]
}
```
Provide information for the fields to add the `UpdateAvailability` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **AvailabilityEndDate** (string) – Date until when the offer is discoverable and purchasable in AWS Marketplace. You can choose to set a specific date in the future to restrict the availability or in the past to expire the offer. Dates are represented in `YYYY-MM-DD` format. Offer expires at 23:59:59.999 UTC on the date provided.
**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 `UpdateAvailability` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| AvailabilityEndDate | Required Format: "YYYY-MM-DD" | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateAvailability` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INVALID\$1AVAILABILITY\$1END\$1DATE | AvailabilityEndDate isn't supported for public offers. |
| INVALID\$1AVAILABILITY\$1END\$1DATE | Provide a future AvailabilityEndDate. |
| INVALID\$1AVAILABILITY\$1END\$1DATE | Provide an AvailabilityEndDate that is before AgreementEndDate. |
| MISSING\$1AVAILABILITY\$1END\$1DATE | Provide an AvailabilityEndDate that is before the agreement's end date. |
## Define the expiration date of agreements
You can use the Catalog API to define the expiration date of the agreements that are created using this offer in AWS Marketplace.
This change does not affect existing agreements. The manufacturer could mention maximum agreement start date in a Resale Authorization. However, channel partners can’t provide an agreement start date later than that date.
To define the expiration date of agreements, call the `StartChangeSet` API operation with the `UpdateValidityTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdateValidityTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "ValidityTerm",
"AgreementDuration": "P12M",
"AgreementStartDate": "2021-08-01",
"AgreementEndDate": "2022-08-01"
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdateValidityTerms` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Terms** (array of structures) **–** List of validity terms that you want to update. Supported validity terms are:
+ **ValidityTerm** (object) **–** Defines the conditions that will keep an agreement, created from this offer, valid.
+ **Type** (string) **–** Category of the term being updated.
+ **AgreementDuration** (string) **–** Defines the duration that the agreement remains active. If `AgreementStartDate` isn’t provided, agreement duration is relative to the agreement signature time. The duration is represented in the ISO\$18601 format.
+ **AgreementStartDate** (string) **–** Defines the date when agreement starts. `AgreementStartDate` is represented in YYYY-MM-DD format. The agreement starts at 00:00:00.000 UTC on the date provided. If `AgreementStartDate` isn’t provided, agreement start date is determined based on agreement signature time.
+ **AgreementEndDate** (string) **–** Defines the date when the agreement ends. The `AgreementEndDate` is represented in YYYY-MM-DD format. The agreement ends at 23:59:59.999 UTC on the date provided. If `AgreementEndDate` isn’t provided, the agreement end date is determined by the validity of individual terms.
**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 `UpdateValidityTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP code |
| --- | --- | --- |
| Terms | Required Only "ValidityTerm" is allowed in the list Must be empty or contain only 1 term | 422 |
| Terms[].ValidityTerm | Supported use cases: 1. ValidityTerm with only AgreementDuration 2. ValidityTerm with only AgreementStartDate 3. ValidityTerm with only AgreementEndDate 4. ValidityTerm with both AgreementStartDate and AgreementEndDate | 422 |
| Terms[].ValidityTerm.AgreementDuration | Optional Represented in ISO\$18601 format. | 422 |
| Terms[].ValidityTerm.AgreementStartDate | Optional Format: "YYYY-MM-DD" | 422 |
| Terms[].ValidityTerm.AgreementEndDate | Optional Format: "YYYY-MM-DD" | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdateValidityTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1AGREEMENT | AgreementStartDate can't be in the future when the current agreement to be replaced isn't future dated. |
| INCOMPATIBLE\$1AGREEMENT\$1END\$1DATE | AgreementEndDate can't be updated after the offer is released. |
| INCOMPATIBLE\$1AGREEMENT\$1START\$1DATE | AgreementStartDate can't be updated after the offer is released. |
| INCOMPATIBLE\$1PRODUCT | AgreementStartDate in the future isn't supported. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the duration between AgreementStartDate and AgreementEndDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure AgreementStartDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure AgreementEndDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the duration between AgreementStartDate and AgreementEndDate is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure AgreementDuration matches duration specified in the ResaleAuthorization. |
| INCOMPATIBLE\$1TERMS | ValidityTerm isn't supported for public offers. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1AGREEMENT\$1DURATION | Provide AgreementDuration that is greater than or equal to [x] days. |
| INVALID\$1AGREEMENT\$1END\$1DATE | Provide a future AgreementEndDate. |
| INVALID\$1AGREEMENT\$1END\$1DATE | Provide AgreementEndDate that is after or equal to [x]. |
| INVALID\$1AGREEMENT\$1START\$1DATE | Provide an AgreementStartDate that is after AvailabilityEndDate. |
| INVALID\$1AGREEMENT\$1START\$1DATE | Provide an AgreementStartDate that is before the AgreementEndDate. |
| INVALID\$1AGREEMENT\$1START\$1DATE | Provide an AgreementStartDate that is within [x] years from today. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with both AgreementDuration and AgreementEndDate isn't supported. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with both AgreementStartDate and AgreementDuration isn't supported in an offer for the product. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with AgreementStartDate isn't supported in an offer for the product. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | ValidityTerm with only AgreementStartDate isn't supported. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | AgreementEndDate isn't supported unless it's used in combination with a future AgreementStartDate or for replacement offers. |
| INVALID\$1AGREEMENT\$1TIME\$1INTERVAL | Provide AgreementStartDate and AgreementEndDate where the difference is less than or equal to [x] years. |
| MISSING\$1AGREEMENT\$1START\$1DATE | Ensure AgreementStartDate is present in ValidityTerm when used along with ConfigurableUpfrontPricingTerm. |
## Update pricing
You can use the Catalog API to replace the existing pricing terms completely.
The pricing terms that aren't included in the latest request will be removed from the offer. Channel partners can use this change type only to pass `FixedUpFrontPricingTerm`.
To update pricing terms for your offers, call the `StartChangeSet` API operation with the `UpdatePricingTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"Details": {
"PricingModel": "Contract",
"Terms": [
{
"Type": "FixedUpfrontPricingTerm",
"CurrencyCode": "USD",
"Price": "200.00",
"Duration": "P465D",
"Grants": [
{
"DimensionKey": "Users",
"MaxQuantity": 10
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdatePricingTerms` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **Details** (string) (required) – Specifics of the request. This field is a JSON string field. It must be formatted properly for a single-line string field, including escaping characters (such as quotation marks) that can’t be in a string.
+ **PricingModel** (string) (required) – Pricing model for your offer. Possible values for pricing model are:
+ **Contract** – Contract-based pricing model where buyers are either billed in advance for the use of your product, or offered a flexible payment schedule. Buyers can also pay for an additional usage above their contract.
+ **Terms** (array of structures) (required) – List of pricing terms that you want to update. Supported pricing terms are:
+ **FixedUpfrontPricingTerm** (object) – Defines a pre-paid pricing model where the customers are charged a fixed upfront amount.
+ **Type** (string) (required) – Type of the term being updated.
+ **CurrencyCode** (string) (required) – Defines the currency for the prices mentioned in this term. For public offers, only USD is supported. For private offers, USD, AUD, EUR, GBP, and JPY are supported.
+ **Price** (string) (required) – Fixed amount to be charged to the customer when this term is accepted.
+ **Grants** (array of structures) (required) – Entitlements that will be granted to the acceptor of fixed upfront as part of agreement execution.
+ **DimensionKey** (string) (required) – Unique dimension key defined in the product document. Dimensions represent categories of capacity in a product and are specified when the product is listed in AWS Marketplace.
+ **MaxQuantity** (integer) (optional) – Maximum amount of capacity that the buyer can be entitled to the given dimension of the product. If `MaxQuantity` is not provided, the buyer will be able to use an unlimited amount of the given dimension.
+ **Duration** (string) (optional) – Defines the duration that the term remains active. This field supports the ISO 8601 format.
**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 `UpdatePricingTerms` 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 will fail with an HTTP response.
| Input field | Validation rule |
| --- | --- |
| PricingModel | Required Allowed pricing models: Contract |
| Terms | Required Allowed terms: FixedUpfrontPricingTerm |
| Terms[].FixedUpfrontPricingTerm.CurrencyCode | Required Allowed values: ["USD", "AUD", "EUR", "GBP", "JPN"] Allowed pricing models: Contract |
| Terms[].FixedUpfrontPricingTerm.Price | Required Data type is "String" Must be non-negative Support up to 6 Decimals No special character supported |
| Terms[].FixedUpfrontPricingTerm.Duration | Required Expected format: ISO 8601 duration |
| Terms[].FixedUpfrontPricingTerm.Grants[].DimensionKey | Required Length must be between 1 and 60 |
| Terms[].FixedUpfrontPricingTerm.Grants[].MaxQuantity | Required |
**Asynchronous Errors**
The following errors are specific to `UpdatePricingTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| DUPLICATE\$1DIMENSION\$1KEYS | Provide Grants with a unique list of dimension keys in [x]. |
| DUPLICATE\$1DIMENSION\$1KEYS | Provide RateCard with a unique list of dimension keys in [x]. |
| DUPLICATE\$1SELECTORS | Provide a unique list of Selectors in ConfigurableUpfrontPricingTerm. |
| DUPLICATE\$1TERM\$1TYPES | Provide a unique list of term types. |
| INCOMPATIBLE\$1AGREEMENT | The following terms can't be removed from the replacement offer: [x, y, z]. |
| INCOMPATIBLE\$1AGREEMENT | The following terms can't be added to the replacement offer: [x, y, z]. |
| INCOMPATIBLE\$1CURRENCY\$1CODE | CurrencyCode can't be changed after the offer is released. |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1PRODUCT | Usage pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | Contract pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | Byol pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | Free pricing model isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | [x] isn't supported in an offer for the product. |
| INCOMPATIBLE\$1PRODUCT | Provided payment and pricing terms are incompatible. |
| INCOMPATIBLE\$1PRODUCT | Use existing, available dimensions in the product in [x]. |
| INCOMPATIBLE\$1PRODUCT | FreeTrialPricingTerm as the offer's only pricing term isn't supported for the product. |
| INCOMPATIBLE\$1PRODUCT | The following terms aren't supported for the product: [x,y,z]. |
| INCOMPATIBLE\$1PRODUCT | Replacement offers are only supported for contract pricing model. |
| INCOMPATIBLE\$1PRODUCT | Provide pricing term(s) that are compatible with the product dimensions. Incompatible pricing terms: [x,y,z]. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | Set MultipleDimensionSelection and QuantityConfiguration to Allowed in ConfigurableUpfrontPricingTerm for usage pricing model. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | Set MultipleDimensionSelection and QuantityConfiguration to Disallowed in ConfigurableUpfrontPricingTerm for usage pricing model. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | QuantityConfiguration in ConfigurableUpfrontPricingTerm can't be changed after the offer is released. |
| INCOMPATIBLE\$1RATE\$1CARD\$1CONSTRAINTS | MultipleDimensionSelection in ConfigurableUpfrontPricingTerm can't be changed after the offer is released. |
| INCOMPATIBLE\$1RATES | Set all charge amounts and prices to zero (0) when using Free pricing model. |
| INCOMPATIBLE\$1RATES | Only zero (0) prices are allowed in UsageBasedPricingTerm for a free trial offer for the product. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide the same CurrencyCode that is specified in the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure Duration in FixedUpfrontPricingTerm matches duration specified in the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide term(s) that are compatible with the ResaleAuthorization. Incompatible terms: [x, y, z]. |
| INCOMPATIBLE\$1SELECTOR\$1DURATION | Durations aren't allowed to be removed from rate cards in ConfigurableUpfrontPricingTerm after the offer released. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INCOMPATIBLE\$1TERMS | [x] isn't supported together with the following terms: [y,z]. |
| INCOMPATIBLE\$1TERMS | The following terms can't be added after the offer is released: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | The following terms can't be removed after the offer is released: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | [x] isn't supported for private offers. |
| INCOMPATIBLE\$1TERMS | The following terms aren't supported with FreeTrialPricingTerm that grants unlimited usage: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | The following terms aren't supported with FreeTrialPricingTerm for the product: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | Provide zero (0) price for FixedUpfrontPricingTerm when the offer contains a PaymentScheduleTerm. |
| INCOMPATIBLE\$1TERMS | The following terms aren't compatible with the PricingModel: [x,y,z]. |
| INCOMPATIBLE\$1TERMS | FixedUpfrontPricingTerm isn't supported when MarkupPercentage is greater than zero (0). |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1AGREEMENT\$1DURATION | Provide duration between [x] and [y] months. |
| INVALID\$1AGREEMENT\$1DURATION | Ensure duration granularity is at the day level for metered dimensions. |
| INVALID\$1CURRENCY\$1CODE | Provide a supported CurrencyCode. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| INVALID\$1DURATION | Ensure Duration in FreeTrialPricingTerm is within the allowed range. |
| INVALID\$1DURATION | Provide Duration in FixedUpfrontPricingTerm that matches the duration between AgreementStartDate and AgreementEndDate. |
| INVALID\$1DURATION | Provide duration between [x] and [y] months. |
| INVALID\$1DURATION | Ensure duration granularity is at the day level for metered dimensions. |
| INVALID\$1GRANTS | Provide the same MaxQuantity for all Grants in FreeTrialPricingTerm. |
| INVALID\$1GRANTS | Provide Grants for all available metered dimensions in FreeTrialPricingTerm. |
| INVALID\$1PRICE\$1CHANGE | [x] can't be updated until [y] because you have requested a price increase in the past 120 days. To cancel your previous price increase request or for more information, contact the AWS Marketplace Managed Catalog Operations Team. |
| INVALID\$1PRICE\$1CHANGE | Price increase and dimension addition in [x] isn't supported in the same request. Add dimensions first. |
| INVALID\$1PRICE\$1CHANGE | Price increase and decrease in UsageBasedPricingTerm isn't supported in the same request. Decrease prices first. |
| INVALID\$1PRICE\$1CHANGE | Price increase in RecurringPaymentTerm and price decrease in UsageBasedPricingTerm isn't supported in the same request. Decrease prices first. |
| INVALID\$1PRICE\$1CHANGE | Price decrease in RecurringPaymentTerm and price increase in UsageBasedPricingTerm isn't supported in the same request. Decrease prices first. |
| INVALID\$1RATE\$1CARD | ConfigurableUpfrontPricingTerm is missing one or more-dimension keys for duration [x]. Provide prices for the same set of dimension keys for all durations. |
| INVALID\$1RATE\$1CARD | Provide a rate card for only metered dimensions in UsageBasedPricingTerm. |
| INVALID\$1RATE\$1CARD | Rates can't be removed from [x]. Provide prices for all dimensions in the existing rate card. |
| INVALID\$1RATE\$1CARD | Provide dimensions that have the same unit in [x]. |
| INVALID\$1RATE\$1CARD | Provide either all metered or all entitled dimensions in [x]. |
| INVALID\$1RATE\$1CARD | Provide only entitled dimensions in [x]. |
| INVALID\$1RATE\$1CARD | Provide usage based rates for all available metered dimensions in UsageBasedPricingTerm. |
| INVALID\$1RATE\$1CARD | Provide usage based rates for all free trial dimensions. |
| INVALID\$1RATE\$1CARD | Provide prices with up to 8 decimal places in UsageBasedPricingTerm. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide duration between [x] and [y] months. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Ensure duration granularity is at the day level for metered dimensions. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Ensure Duration in ConfigurableUpfrontPricingTerm is within the allowed range. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide one or more supported contract durations. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide one or more supported contract durations or a single custom duration. |
| INVALID\$1SELECTOR\$1DURATION\$1VALUE | Provide Duration in ConfigurableUpfrontPricingTerm that matches the duration between AgreementStartDate and AgreementEndDate. |
| MISSING\$1DURATION | Provide Duration in FixedUpfrontPricingTerm. |
| MISSING\$1MANDATORY\$1TERMS | FixedUpfrontPricingTerm is only supported when paired with ByolPricingTerm or PaymentScheduleTerm. |
| MISSING\$1MANDATORY\$1TERMS | Provide at least one of [x,y,z]. |
| MISSING\$1MANDATORY\$1TERMS | Provide a ByolPricingTerm when using Byol pricing model. |
| TOO\$1MANY\$1GRANTS | Provide up to [x] grants in [y]. |
| TOO\$1MANY\$1RATE\$1CARDS | Only one rate card in ConfigurableUpfrontPricingTerm is allowed for the product. |
| TOO\$1MANY\$1RATE\$1CARDS | Up to [x] rate cards are allowed in ConfigurableUpfrontPricingTerm for the product. |
| TOO\$1MANY\$1RATES | Provide RateCards within the allowed limits in ConfigurableUpfrontPricingTerm. |
| TOO\$1MANY\$1RATES | Provide RateCards within the allowed limits in UsageBasedPricingTerm. |
## Update payment schedule details
You can use the Catalog API to change the payment schedule details, such as flexible payment schedule, in AWS Marketplace.
If the manufacturer has provided a payment schedule in Resale Authorization, Channel Partner can either:
+ Use the `UpdateMarkup` change type to apply a uniform percentage markup to all payment schedules.
+ Use the `UpdatePaymentScheduleTerms` change type to set custom payment amounts to a value greater than or equal to what is provided in Resale Authorization. Payment dates can't be changed. Both options can't be applied simultaneously. If a markup is applied first and you need to change it to apply a payment schedule, set the markup to `0` through the `UpdateMarkup` change type. If a payment schedule is applied first you can't revert the change to apply the markup.
To update payment-associated details for your offer, call the `StartChangeSet` API operation with the `UpdatePaymentScheduleTerms` change type, as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "UpdatePaymentScheduleTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {
"Terms": [
{
"Type": "PaymentScheduleTerm",
"Schedule": [
{
"ChargeDate": "2021-12-01",
"ChargeAmount": "200.00"
},
{
"ChargeDate": "2022-03-01",
"ChargeAmount": "250.00"
}
]
}
]
}
}
]
}
```
Provide information for the fields to add the `UpdatePaymentScheduleTerms` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request.
+ **Terms** (array of structures) – List of payment terms that you want to update. Supported payment terms are:
+ **PaymentScheduleTerm** (object) – Defines an installment-based pricing model where customers are charged a fixed price on different dates during the agreement validity period.
+ **Type** (string) – Type of the term being updated. This is the object value: `"PaymentScheduleTerm"`.
+ **Schedule** (array of structures) – List of the payment schedule where each element defines one installment of payment. It contains the information necessary for calculating the price to be paid and the date on which the customer would be charged.
+ **ChargeDate** (string) – The date on which the customer would pay the price defined in this payment schedule term. `ChargeDate` is represented in YYYY-MM-DD format. Invoices are generated on the date provided.
+ **ChargeAmount ** (string) – The price that the customer would pay on scheduled date (`ChargeDate`).
**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 `UpdatePaymentScheduleTerms` 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 will fail with an HTTP response.
| Input field | Validation rule | HTTP |
| --- | --- | --- |
| Terms | Required Only "PaymentScheduleTerm" is allowed List size must be less than 2 | 422 |
| Terms[].PaymentScheduleTerm.CurrencyCode | Required Supported currencies: ["USD", "AUD", "EUR", "GBP", "JPN"] | 422 |
| Terms[].PaymentScheduleTerm.Schedule[] | Required List size must be between 1 and 60, inclusive | 422 |
| Terms[].PaymentScheduleTerm.Schedule[].ChargeDate | Required Format: "YYYY-MM-DD" | 422 |
| Terms[].PaymentScheduleTerm.Schedule[].ChargeAmount | RequiredData type is "String"Non-negative decimals with up to 2 decimal places supportedNo additional properties are allowed | 422 |
**Asynchronous Errors**
The following errors are specific to `UpdatePaymentScheduleTerms` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| DUPLICATE\$1CHARGE\$1DATES | Provide unique charge dates in PaymentScheduleTerm. |
| INCOMPATIBLE\$1MARKUP\$1PERCENTAGE | PaymentScheduleTerm isn't supported when MarkupPercentage is greater than zero (0). |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide term(s) that are compatible with the ResaleAuthorization. Incompatible terms: [PaymentScheduleTerm]. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the total ChargeAmounts in PaymentScheduleTerm is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the charge dates in PaymentScheduleTerm are same as the charge dates in the ResaleAuthorization. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the charge amount in PaymentScheduleTerm is greater than or equal to the charge amount in the ResaleAuthorization for that date. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INCOMPATIBLE\$1TERMS | Use either UpdatePaymentScheduleTerms with specific payment amount or UpdateMarkup with a single markup percentage for the scheduled dates. |
| INVALID\$1CHARGE\$1DATES | Provide charge dates before AgreementEndDate. |
| TOO\$1MANY\$1BACKDATED\$1CHARGES | Provide up to 1 scheduled payment before AvailabilityEndDate. |
| Error code | Error message |
| --- | --- |
| DUPLICATE\$1CHARGE\$1DATES | Provide unique charge dates in PaymentScheduleTerm. |
| INCOMPATIBLE\$1CURRENCY\$1CODE | CurrencyCode can't be changed after the offer is released. |
| INCOMPATIBLE\$1MARKUP\$1PERCENTAGE | PaymentScheduleTerm isn't supported when MarkupPercentage is greater than zero (0). |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Provide term(s) that are compatible with the ResaleAuthorization. Incompatible terms: [PaymentScheduleTerm]. |
| INCOMPATIBLE\$1RESALE\$1AUTHORIZATION | Ensure the total ChargeAmounts in PaymentScheduleTerm is compatible with the ResaleAuthorization. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is released. |
| INCOMPATIBLE\$1TERMS | The requested change can't be performed after the offer is expired. |
| INVALID\$1CHARGE\$1DATES | Provide charge dates before AgreementEndDate. |
| INVALID\$1CURRENCY\$1CODE | Provide a supported CurrencyCode. |
| INVALID\$1CURRENCY\$1CODE | Provide the same CurrencyCode across all pricing and payment terms. |
| TOO\$1MANY\$1BACKDATED\$1CHARGES | Provide up to 1 scheduled payment before AvailabilityEndDate. |
## Publish the CPPO
You can use the Catalog API to merge the information collected from all update change types, and then publish the offer in AWS Marketplace.
Offers remain in a `Draft` state, until `ReleaseOffer` is called. After the offer is released, it’s discoverable in AWS Marketplace.
To publish your offer, call the `StartChangeSet` API operation with the `ReleaseOffer` change type as shown in the following example.
**Request Syntax**
```
POST /StartChangeSet HTTP/1.1
Content-type: application/json
{
"Catalog": "AWSMarketplace",
"ChangeSet": [
{
"ChangeType": "ReleaseOffer",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "offer-123456789"
},
"DetailsDocument": {}
}
]
}
```
Provide information for the fields to add the `ReleaseOffer` change type:
+ **Entity** (object) (required) – Your CPPO.
+ **Type** (string) (required) – The `Type` is always `Offer@1.0`.
+ **Identifier** (string) (required) – Your offer ID. For more information, see [Identifier](catalog-apis.md#identifier).
+ **DetailsDocument** (object) (required) – The JSON value of specifics of the request. It must be empty for `ReleaseOffer`.
**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 `ReleaseOffer` 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 will fail with an HTTP response.
| Input field | Validation rule |
| --- | --- |
| Details | Must be empty (\$1\$1) |
**Asynchronous Errors**
The following errors are specific to `ReleaseOffer` actions in the AWS Marketplace Catalog API. These errors are returned when you call `DescribeChangeSet` after a change set is processing. For more information about using `DescribeChangeSet` to get the status of a change request, see [Working with change sets](catalog-apis.md#working-with-change-sets).
| Error code | Error message |
| --- | --- |
| INCOMPATIBLE\$1PAYMENT\$1SETTINGS | Update your payment settings to be compatible with the CurrencyCode. |
| INCOMPATIBLE\$1PRODUCT | First create a public offer for the product. |
| INCOMPATIBLE\$1SELLER\$1VERIFICATION | Complete all required seller verification processes. |
| INVALID\$1UPDATE\$1REQUEST | The requested change can't be performed after the offer is released. |
| MISSING\$1AGREEMENT\$1END\$1DATE | Provide an AgreementEndDate for replacement offers. |
| MISSING\$1AVAILABILITY\$1END\$1DATE | Provide an AvailabilityEndDate for private offer. |
| MISSING\$1MANDATORY\$1TERMS | Provide a FixedUpfrontPricingTerm when the offer contains a PaymentScheduleTerm. |
| MISSING\$1BUYER\$1ACCOUNTS | Provide PositiveTargeting with BuyersAccounts for offers created using ResaleAuthorization. |
| MISSING\$1BUYER\$1ACCOUNTS | All offers for the product must be private. Provide PositiveTargeting with BuyersAccounts. |
| MISSING\$1DESCRIPTION | Set Description before releasing the offer. |
| MISSING\$1MANDATORY\$1TERMS | Add [x] to the offer. |
| MISSING\$1MANDATORY\$1TERMS | Provide a FixedUpfrontPricingTerm when the offer contains a PaymentScheduleTerm. |
| MISSING\$1NAME | Set Name before releasing the offer. |
| TOO\$1MANY\$1OFFERS | Only one public offer can be created per product. |
| TOO\$1MANY\$1OFFERS | Only one public free trial offer can be created per product. |
## Define an existing CPPO
You can use the Catalog API to define CPPO details in AWS Marketplace.
To define an existing CPPO, call the `DescribeEntity` API operation with the `Offer@1.0` entity type, as shown in the following example.
**Request Syntax**
```
GET /DescribeEntity?catalog=&entityId= HTTP/1.1
```
Provide information for the fields to add the `DescribeEntity` change type:
+ **catalog** (string) –The catalog related to the request. Fixed value: `AWSMarketplace`.
+ **entityId** (string) – The unique ID of the offer to describe.
**Response Syntax**
The response to this request gives you the offer details and looks like the following.
```
{
"EntityType": "Offer@1.0",
"EntityIdentifier": "offer-a5oEXAMPLEzpu@1",
"EntityArn": "arn:aws:aws-marketplace:us-east-1:446235747164:AWSMarketplace/Offer/offer-a5oEXAMPLEzpu",
"LastModifiedDate": "2021-03-10T21:57:16Z",
"Details": {
"Id": "offer-3rEXAMPLErn",
"State": "Released",
"Name": "Test Offer",
"Description": "Worldwide private offer for Test Product",
"PreExistingAgreement": {
"AcquisitionChannel": "External",
"PricingModel": "Contract"
},
"ProductId": "prod-0bEXAMPLEb51",
"ResaleAuthorizationId": "resaleauthz-123456789",
"MarkupPercentage": "5.0",
"Terms": [
{
"Type": "LegalTerm",
"Documents": [
{
"Type": "CustomEula",
"Url": "https://s3.amazonaws.com/EULA/custom-eula-1234.txt"
}
]
},
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P12M"
},
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "300.00"
},
{
"DimensionKey": "m4.xlarge",
"Price": "400.00"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
},
{
"Type": "UsageBasedPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"RateCard": [
{
"DimensionKey": "m3.large",
"Price": "0.10"
},
{
"DimensionKey": "m4.xlarge",
"Price": "0.20"
}
]
}
]
},
{
"Type": "PaymentScheduleTerm",
"CurrencyCode": "USD",
"Schedule": [
{
"ChargeDate": "2020-12-01T00:00:00Z",
"ChargeAmount": "1000.00"
},
{
"ChargeDate": "2021-06-15T00:00:00Z",
"ChargeAmount": "1250.00"
}
]
}
],
"Rules": [
{
"Type": "TargetingRule",
"PositiveTargeting": {
"CountryCodes": [
"US",
"CA"
],
"BuyerAccounts": [
"118033953248"
]
},
"NegativeTargeting": {
"CountryCodes": [
"XX"
]
}
},
{
"Type": "AvailabilityRule",
"AvailabilityEndDate": "2050-08-30T01:56:03Z"
}
]
}
}
```
Provide information for the input fields for the `DescribeEntity` response:
+ **EntityType** (string) – The named type of the entity, which is `Offer@1.0`.
+ **EntityIdentifier** (string) – The identifier of the entity, in the format of `EntityId@RevisionId`.
+ **EntityArn** (string) – The ARN associated to the unique identifier for the change set referenced in this request.
+ **LastModifiedDate** (string) – The last modified date of the entity, in ISO 8601 format (`2018-02-27T13:45:22Z`).
+ **DetailsDocument** (object) – The JSON object includes the details of the entity.
+ **Id** (string) – Unique identifier for an offer entity in AWS Marketplace and is generated during the creation of an offer.
+ **State** (string) – The status of the offer.
+ **Name** (string) – Name associated with the offer for better readability to you and your customers. It will be displayed as part of Agreement information as well.
+ **Description** (string) – Description is a free-form text which is meant to be used only by you and will never be exposed to buyers.
+ **PreExistingAgreement** (string) – 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) – Indicates if the existing agreement was signed outside AWS Marketplace or within AWS Marketplace. Possible values: `External`, `AwsMarketplace`.
+ **PricingModel** (string) – Indicates which pricing model the existing agreement uses. Possible values: `Contract`, `Usage`, `Byol`, `Free`.
+ **ProductId** (string) – Description is a free-form text which is meant to be used only by you and will never be exposed to buyers.
+ **ResaleAuthorizationId** (string) – ResaleAuthorization is used to create the private offer.
+ **MarkupPercentage** (string) – Percentage value that the channel partner passed in the `UpdateMarkup` change type. This markup is already applied to the terms.
+ **Terms** (array of structures) – List of terms.
+ **Rules** (array of structures) – List of rules.
# Work with renewals
Renewals in AWS Marketplace enable sellers, including independent software vendors (ISVs) and channel partners, to seamlessly extend existing agreements with customers. During the renewal process, sellers have the option to adjust terms by creating a new offer.
There are four types of renewals in AWS Marketplace:
+ **Agreement based offers**: Sellers can replace an existing agreement to adjust pricing, duration, terms, and renew an existing contract before it ends. An agreement based offer can be extended to the customer beyond the current agreement’s end date, granting new entitlements, discounts, or payment schedules based on the customers needs.
This support applies to software as a service (SaaS) products, including those with contract and consumption-based pricing (CCP), whether they offer flexible payment options or not.
+ **Future dated offers**: Sellers can create future dated offers to start on a date in the future, and use them to pre-book renewals while existing terms are still ongoing. Once accepted by the customer, the agreement begins on a specified **future date, allowing to start after the current agreement ends.**
This support applies to software as a service (SaaS) products, including those with contract and consumption-based pricing (CCP), whether they offer flexible payment options or not.
+ **New private offer**: Sellers can [create a new private offer](work-with-private-offers.md#create-offer) with new terms (for AMI hourly, AMI annual, and SaaS pay-as-you-go subscriptions) that can be accepted anytime to renew an existing agreement.
+ **Auto-renewal**: Customers can enable auto-renewal for public offers and AWS Data Exchange products with private offers to automatically create a new agreement when a previous agreement ends.
**Topics**
+ [
## Replacement offers
](#replacement-offers)
+ [
## Future dated agreements
](#future-dated-offers)
+ [
## Resources
](#renewals-resources)
## Replacement offers
As a seller, you can offer renewals by replacing an active agreement that was originally created when the customer accepted your public offer or private offer. Using a replacement offer, you can extend a new offer to the customer that goes beyond the current agreements end date, grant new entitlements, offer pricing discounts, adjust payment schedules, change the payment schedule, or change the end user license agreement (EULA).
You can use the Catalog API to [create a replacement offer](https://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-private-offers.html#create-replacement-offer) (also known as an agreement-based offer) in AWS Marketplace for [supported product types](https://docs.aws.amazon.com/marketplace/latest/userguide/private-offers-upgrades-and-renewals.html#private-offers-upgrades-and-renewals-supported-products). You will need to provide the unique identifier (agreement ID) of the current agreement you wish to replace. You can find this agreement ID in the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management) under the Agreements section or by using the [SearchAgreements](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-agreements_SearchAgreements.html) API operation.
Once the customer accepts the replacement offer, their current agreement will be replaced with a new agreement that can extend beyond the previous end date.
**Note**
You cannot create a replacement agreement that specifies a seller of record that differs from the original agreement.
For more information on replacement offers, see [Amending private offers in AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/userguide/private-offers-upgrades-and-renewals.html) in the *AWS Marketplace Seller Guide*.
## Future dated agreements
Future-dated agreements are created when a customer accepts a private offer with a future service start date. To facilitate advance booking of upcoming renewals in AWS Marketplace, ISVs and channel partners can create private offers that start the day after the current agreement ends rather than immediately upon acceptance.
To set the start date of a renewal agreement as the day after the end date of the current agreement, you can use the [Catalog API UpdateValidityTerms change type](https://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-private-offers.html#update-validity-terms) on a private offer that has already been published. Sellers can choose a service start date up to three years in the future.
Customers can review the terms and conditions of the private offer and accept it before it takes effect. Accepting a private offer with a start date in the future does not replace the current agreement. Instead, it creates a renewal agreement that begins immediately after the previous agreement ends.
For more information on product types that support future dated offers and agreements, see [Creating future dated agreements](https://docs.aws.amazon.com/marketplace/latest/userguide/private-offers-seller-future-dated-private-offers-and-agreements.html#seller-creating-future-dated-agreements) in the *AWS Marketplace Seller Guide*.
## Resources
+ For end-to-end labs with working code examples, see:
+ [Lab: Create a private offer (with a future service start date)](https://catalog.workshops.aws/mpseller/en-US/manage-offers-with-api/create-a-private-offer-with-a-future-service-start-date)
+ [Lab: Create a replacement private offer](https://catalog.workshops.aws/mpseller/en-US/manage-offers-with-api/create-a-replacement-private-offer)
+ For a video on creating replacement offers, see [Renew SaaS Contract Private Offers - AWS Marketplace](https://www.youtube.com/watch?v=KzcE0ZWyjzk) on YouTube.
+ For a video on creating future dated offers, see [Create an AWS Marketplace Future Dated Private Offer](https://www.youtube.com/watch?v=xLqQjXa2edo) on YouTube.