# Work with machine learning products using AWS Marketplace APIs Work with machine learning products You can use the AWS Marketplace Catalog API to automate tasks for managing machine learning (ML)-based products. This section covers key operations for ML products using the Catalog API. For information about creating machine learning products using the Catalog API, refer to [ Listing your product in AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-publishing-your-product-in-aws-marketplace.html) in the *AWS Marketplace Seller Guide*. **Topics** + [ # Prerequisites for publishing ML product listings ](cat-ml-prereqs.md) + [ # Add a new version ](ml-add-version.md) + [ # Update version information ](ml-update-version.md) + [ # Update pricing terms ](update-pricing-terms.md) + [ # Restrict a version ](ml-restrict-version.md) # Prerequisites for publishing ML product listings Ensure that you have the following before getting started with publishing your machine learning product listing: + Registration as a seller in AWS Marketplace. For more information, refer to [Register as an AWS Marketplace seller](https://docs.aws.amazon.com/marketplace/latest/userguide/seller-registration-process.html). + An IAM user with `AWSMarketplaceSellerFullAccess` permission. + A publicly accessible Amazon Simple Storage Service (Amazon S3) bucket to host your company logo and EULA, if you provide one. You enter the URL for the S3 bucket in your `ChangeSet` JSON file. + A valid SageMaker AI ARN of the model package or algorithm resource you want to list. + A valid IAM role that has a trust relationship with the AWS Marketplace service principal and provides access to your package. For more information about the role, refer to *IAM role for the AWS Marketplace service principal* in the [Prerequisites](https://docs.aws.amazon.com/marketplace/latest/userguide/ml-publishing-prereq.html) page for machine learning products. # Add a new version Add a new version You can use the Catalog API or the AWS Marketplace Management Portal to add a new version to a machine learning product. For more information about using the portal, refer to [Adding a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/machine-learning-products.html) in the *AWS Marketplace Seller Guide*. **Note** For ML products, a version consists of a single delivery option, which represents the product you're making available. In the Catalog API, working with delivery options for ML products effectively modifies versions of your product. When adding new instance types, include an `UpdatePricingTerms` change type in your change set to specify pricing for new instance types. For new products, `UpdatePricingTerms` must cover all supported instance types. `UpdatePricingDimensions` is not required or supported for ML products, because dimensions are automatically generated for all supported instance types. For more information, refer to [Update pricing dimensions](work-with-seller-products.md#update-dimensions). **Using `StartChangeSet` to add a version** To add a new version, call the `StartChangeSet` operation with the `AddDeliveryOptions` change type: 1. To validate your API call without creating a version, set `Intent` to `VALIDATE`. 1. For actual version creation, set `Intent` to `APPLY`. ## Request syntax ``` POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [{ "ChangeType": "AddDeliveryOptions", "Entity": { "Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1", "Type": "MachineLearningProduct@1.0" }, "DetailsDocument": { "Version": { "VersionTitle": "version 1.1", "ReleaseNotes": "Patch update for small bugfix in version 1.0" }, "DeliveryOptions": [{ "Details": { "SageMakerAlgorithmDeliveryOptionDetails": { "SageMakerAlgorithmArn": "arn:aws:sagemaker:us-east-2:605142612156:algorithm/scikit-decision-trees-1552343220", "AccessRoleArn": "arn:aws:iam::12345678901:role/AwsMarketplaceSageMakerIngestion", "UsageInstructions":"This is how you use your algorithm", "SampleNotebookUrl": "https://www.amazon.com", "RepositoryUrl": "https://www,amazon.com", "InputProperties": { "Description": "Input should have all columns in the train/test file except for 'is_fraud' column.", "Limitations": "Can predict on 1 input in the CSV only at a time", "SampleInput": { "RealtimeInferenceText": "{\"prompt\":\"Write summary\", \"maxTokens\": 1 }", "BatchTransformUrl": "https://www.sampleData.com", }, "Parameters": [{ "Name": "prompt", "Description": "Represents the instruct-style prompt for the model. DataType is String", "Constraints": "Minimum length should be 1", "Required": true }, { "Name": "maxTokens", "Description": "Denotes the number of tokens to predict per generation. See BPE Tokens for more details.", "Constraints": "Minvalue: 1, MaxValue: 30" } ], "SageMakerCustomAttributes": [{ "Name": "threshold", "Description": "Threshold of the confidence score of the detected object", "Constraints": "Should be an Integer" }] }, "OutputProperties": { "Description": "The output is a JSON object that has the generated text along with likelihoods of tokens, if requested. See example json.", "SampleOutput": { "RealtimeInferenceUrl": "https://www.sampledata.com", "BatchTransformUrl": "https://www.sampleData.com", }, "Parameters": [{ "Name": "id", "Description": "An identifier for response" "AlwaysReturned": true }, { "Name": "generations", "Description": "The generated text along with the likelihoods for tokens requested.", } ], }, "RecommendedInstanceTypes": { "BatchTransform": "ml.m4.large", "RealtimeInference": "ml.m4.large", "Training": "ml.m4.large" } } }] } }], "Intent": "APPLY" } ``` ## Required fields + `Entity` (object)—required Contains information about your ML product. + `Identifier` (string)—required Your product ID. For more information, see [Identifier](https://docs.aws.amazon.com/marketplace/latest/APIReference/catalog-apis.html#identifier). + `Type` (string)—required Specifies the delivery method (product type). It must be `MachineLearningProduct@1.0`. + `DetailsDocument` (object)—required Contains all details about the new version of your product. + `Version` (object)—required Details about the version being added. + `VersionTitle` (string)—required The title of the version, such as "Version 1.1" or "1.1". Buyers select versions from these titles. + `ReleaseNotes` (string)—required Detailed notes about this version. Must be under 30,000 characters. + `DeliveryOptions` (array)—required Array of delivery methods for your product version. Limited to one delivery option per version. + `Details` (object)—required + `SagemakerModelPackageDeliveryOptionDetails` or `SageMakerAlgorithmDeliveryOptionDetails` (object) + `SageMakerModelPackageArn` or `SageMakerAlgorithmArn` (string)—required Amazon Resource Name (ARN) of your model package or algorithm. + `AccessRoleArn` (string)—required IAM role ARN for AWS Marketplace to access the SageMaker resource. + `SampleNotebookUrl` (string)—required Link to sample Jupyter notebook with usage code. For more information, refer to a [sample notebook template](https://github.com/aws/amazon-sagemaker-examples/blob/master/aws_marketplace/curating_aws_marketplace_listing_and_sample_notebook/ModelPackage/Sample_Notebook_Template/title_of_your_product-Model.ipynb) on GitHub. + `RepositoryUrl` (string)—required Git repository URL for notebook and sample data access. For more information, see a [sample Git repository](https://github.com/aws/amazon-sagemaker-examples/tree/master/aws_marketplace/curating_aws_marketplace_listing_and_sample_notebook/ModelPackage/Sample_Notebook_Template) on GitHub. + `UsageInstructions` (string)—required Training information for algorithms or usage details for models. + `InputProperties` (object)—required + `Description` (string)—required Description of model/algorithm inputs + `Limitations` (string) Input limitations + `SampleInput` (object)—required RealtimeInferenceUrl (string) \$1 RealtimeInferenceText (string) \$1 BatchTransformUrl (string) \$1 BatchTransformText (string) + `Parameters` (Array) Name (string)—required \$1 Description (string)—Required \$1 Constraints (string) \$1 Required (boolean) + `SageMakerCustomAttributes` (Array) Describes any [CustomAttributes](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#API_runtime_InvokeEndpoint_RequestParameters) supported by your model. `Name` (string)—required \$1 `Description` (string)—Required \$1 `Constraints` (string) \$1 `Required` (boolean) + `OutputProperties` (object)—required + `Description` (string)—required + `SampleOutput` (Array)—required RealtimeInferenceUrl (string) \$1 RealtimeInferenceText (string) \$1 BatchTransformUrl (string) \$1 BatchTransformText (string) + `Parameters` (Array) Name (string)—required \$1 Description (string)—required \$1 AlwaysReturned (boolean) + `RecommendedInstanceTypes` (object)—required + `BatchTransform` (string)—Required + `RealtimeInference` (string)—Required + `Training` (string)—Required for SageMaker Algorithms only ## Response syntax When you submit the request, a change set is created and the API returns: ``` { "ChangeSetId": "example123456789012abcdef", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef" } ``` **Change set processing** The change request enters a processing queue, where it undergoes several steps: 1. Validation: The system checks to ensure all information meets AWS Marketplace guidelines. + Processing time: Few minutes to several hours + For validation errors, see [Change set status and errors](https://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-seller-products.html#seller-product-change-set-errors). 1. Status monitoring: You can check the status of the request two ways. + Via AWS Marketplace Management Portal + Using the `DescribeChangeSet` operation 1. Completion: When approved, the new version is added. ## Errors **Asynchronous errors** The following errors are specific to `AddDeliveryOptions` actions in the AWS Marketplace Catalog API. These errors appear when you call `DescribeChangeSet` while a change set is being processed. For more information about using `DescribeChangeSet` to check the status of a change request, see [Working with change sets](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/welcome.html#working-with-change-sets). | Error code | Error message | | --- | --- | | INCOMPATIBLE\$1PRODUCT\$1STATUS | We couldn't locate the provided product. Provide a valid product. | | DUPLICATE\$1VERSION\$1TITLE | The provided version title is already in use. Create a unique version title. | | INVALID\$1RECOMMENDED\$1INSTANCE\$1TYPE | You didn't provide a valid instance type for [x]. Enter a valid instance type and try again. Valid types are: [valids] | | INCOMPATIBLE\$1DELIVERY\$1OPTIONS | The delivery option you provided doesn't match your previous selection: [previous selection]. Update your delivery option and try again. | | INVALID\$1ASSET\$1ARN | You didn't provide a valid ARN for SageMakerAlgorithmDeliveryOption. Enter a valid ARN and try again. | | DUPLICATE\$1ASSET | You didn't provide a unique ARN for this product. Enter a unique ARN and try again. | | ASSET\$1NOT\$1FOUND | We couldn't locate the ARN you provided. Verify that the ARN is correct and has the required permissions. | | ASSET\$1VALIDATION\$1EXCEPTION | Unable to ingest SagemakerModelArn/SagemakerAlgorithmArn [x] into AWS Sagemaker account | | INVALID\$1ACCESS\$1ROLE | We couldn't locate the IAM role ARN you provided. Verify that the ARN is correct and try again. | | UPDATE\$1PRICING\$1REQUIRED | UpdatePricingTerms is required. | # Update version information Update version information You can use the Catalog API to update details of an existing version of your machine learning product in AWS Marketplace. **Important** You cannot update the ARN for a version. If you need to modify the ARN, you must create a new version instead. **Using `StartChangeSet` to add a version:** + To update version information, call the `StartChangeSet` operation with the `UpdateDeliveryOptions` change type. ## Request syntax ``` POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "UpdateDeliveryOptions", "Entity": { "Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1", "Type": "MachineLearningProduct@1.0" }, "DetailsDocument": { "Version": { "ReleaseNotes": "Adding support for new parameters" }, "DeliveryOptions": [ { "Id": "example1-2222-cccc-2222-cccccccccccc", "Details": { "SagemakerModelPackageDeliveryOptionDetails": { "SampleNotebookUrl": "https://www.amazon.com", "RepositoryUrl":"https://www,amazon.com", "InputProperties": { "SampleInput": { "RealtimeInferenceUrl": "https://www.sampleData.com", "BatchTranformUrl": "https://www.sampleData.com", }, }, "RecommendedInstanceTypes": { "BatchTransform": "ml.m4.large", "RealtimeInference": "ml.m4.large" } } } ] } } ] } ``` ## Required fields + `Entity` (object)—required Contains information about your ML product. + `Identifier` (string)—required Your product ID. For more information, see [Identifier](https://docs.aws.amazon.com/marketplace/latest/APIReference/catalog-apis.html#identifier). + `Type` (string)—required Specifies the delivery method (product type). It must be `MachineLearningProduct@1.0`. + `DetailsDocument` (object)—required Contains the updated version information. + `Version` (object)—required Defines version-specific information. + `VersionTitle` (string)—required The version identifier displayed to buyers, such as "Version 1.1" or "1.1". Buyers use this title to select versions for deployment. + `ReleaseNotes` (string)—required Detailed notes about this version, limited to 30,000 characters. + `DeliveryOptions` (array)—required Specifies delivery methods for your product version. Limited to one delivery option per version. + `Id` (string)—required Unique identifier for the DeliveryOption. Retrieve this using the DescribeEntity action on your product. + `Details` (object)—required Contains the delivery option specifications. + `SageMakerModelPackageSubscriptionDetails` or `SageMakerAlgorithmSubscriptionDetails` (object)—required Details of the delivery option. + `SampleNotebookUrl` (string)—required Sample Jupyter notebook link providing code for buyer usage. + `RepositoryUrl` (string)—required Git repository URL for cloning notebook and sample data. + `UsageInstructions` (string)—required For algorithms: training information. For models: additional usage information. + `InputProperties` (object)—required Details of the model/algorithm's input requirements. + `Description` (string)—required Description of required inputs. + `Limitations` (string) Any input limitations. + `SampleInput` (object)—required Sample input data for different operations. + `RealtimeInferenceUrl` (string) Sample input URL for realtime inference. + `RealtimeInferenceText` (string) Sample input text for realtime inference. + `BatchTransformUrl` (string) Sample input URL for batch transform jobs. + `BatchTransformText` (string) Sample input text for batch transform jobs. + `Parameters` (Array) Details for each input parameter. + `Name` (string)—required Name of the input parameter. + `Description` (string)—required Description of the input parameter. + `Constraints` (string) Parameter constraints (MinValue, MaxValue, AllowedValues, MinLength, MaxLength, Pattern, etc.). + `Required` (boolean) Indicates if the parameter is required. Default is false. + `SageMakerCustomAttributes` (Array) Details for supported CustomAttributes. + `Name` (string)—required Name of the custom attribute. + `Description` (string)—required Description of the custom attribute. + `Constraints` (string) Attribute constraints (MinValue, MaxValue, AllowedValues, MinLength, MaxLength, Pattern, etc.). + `Required` (boolean) Indicates if the attribute is required. Default is false. + `OutputProperties` (object)—required Details of the model/algorithm's output. + `Description` (string)—required Description of model/algorithm outputs. + `SampleOutput` (Array)—required Sample output data for different operations. + `RealtimeInferenceUrl` (string) Sample output URL for realtime inference. + `RealtimeInferenceText` (string) Sample output text for realtime inference. + `BatchTransformUrl` (string) Sample output URL for batch transform jobs. + `BatchTransformText` (string) Sample output text for batch transform jobs. + `Parameters` (Array) Details for each output parameter. + `Name` (string)—required Name of the output parameter. + `Description` (string)—required Description of the output parameter. + `AlwaysReturned` (boolean) Indicates if the parameter is always returned. Default is false. + `RecommendedInstanceTypes` (object)—required Recommended instance types for optimal performance. + `BatchTransform` (string)—required Recommended instance type for batch transform operations. + `RealtimeInference` (string)—required Recommended instance type for realtime inference operations. + `Training` (string)—required Recommended instance type for algorithm training operations. Required only for SageMaker Algorithms. ## Response syntax A successful request returns: ``` { "ChangeSetId": "example123456789012abcdef", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef" } ``` **Change set processing** The change request enters a processing queue, where it undergoes several steps: 1. Validation: The system checks if all information meets AWS Marketplace guidelines. + Processing time: Few minutes to several hours + For validation errors, see [Change set status and errors](https://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-seller-products.html#seller-product-change-set-errors). 1. Status monitoring: You can check the status of the request two ways. + Via AWS Marketplace Management Portal + Using the `DescribeChangeSet` operation 1. Completion: When approved, the new version is updated. ## Errors **Asynchronous errors** Specific errors for `UpdateDeliveryOptions` actions can be retrieved using the `DescribeChangeSet` operation after the change set begins processing. For error details and troubleshooting, see [ Change set status and errors](https://docs.aws.amazon.com/marketplace/latest/APIReference/catalog-apis.html#working-with-change-sets). | Error code | Error message | | --- | --- | | INCOMPATIBLE\$1PRODUCT\$1STATUS | Use an existing limited or public product. | | INVALID\$1DELIVERY\$1OPTION\$1ID | Provide delivery option IDs that can be found in the product. IDs not found: [x] | | INCOMPATIBLE\$1DELIVERY\$1OPTION\$1STATUS | The delivery option cannot be updated because it's in restricted status. Try adding a new version instead. | | INCOMPATIBLE\$1DELIVERY\$1OPTIONS | Product previously used [X ] as delivery option, therefore all the upcoming delivery options should be of type [X] | | INVALID\$1RECOMMENDED\$1INSTANCE\$1TYPE | Provide an existing, available instance type for [X] (X can be Batch Transform, Realtime Inference or ALgorithm Training) | | DUPLICATE\$1VERSION\$1TITLE | The version title must be different from any other version titles of this product. | | FIELD\$1NOT\$1ALLOWED\$1TO\$1CHANGE | Field X is not allowed to be changed. | # Update pricing terms You can use the Catalog API to update the pricing of your machine learning products in AWS Marketplace. **Note** You must price all supported instance types of your machine learning products. When creating your first version, the `UpdatePricingTerms` and `AddDeliveryOptions` change types with prices for all supported instances types in order to publish your product. When adding a new version to an existing product with new instance types that were not supported before, you must include those instance types in the `UpdatePricingTerms` and `AddDeliveryOptions` change types. To update pricing terms, call the `StartChangeSet` operation with the `UpdatePricingTerms` change type. ## Request syntax ``` POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "UpdatePricingTerms", "Entity": { "Type": "Offer@1.0", "Identifier": "$CreateOfferChange.Entity.Identifier" }, "DetailsDocument": { "PricingModel": "Usage", "Terms": [ { "Type": "UsageBasedPricingTerm", "CurrencyCode": "USD", "RateCards": [ { "RateCard": [ { "DimensionKey": "ml.m4.4xlarge.m.i.b", "Price": 0.1 }, { "DimensionKey": "ml.m5.4xlarge.m.i.b", "Price": 0.1 }, { "DimensionKey": "ml.m4.16xlarge.m.i.b", "Price": 0.1 }, { "DimensionKey": "m.i.c", "Price": 0.1 }, { "DimensionKey": "ml.m4.4xlarge.a.t", "Price": 0.1 }, { "DimensionKey": "ml.m5.4xlarge.a.t", "Price": 0.1 }, { "DimensionKey": "ml.m4.16xlarge.a.t", "Price": 0.1 } ] } ] }, { "Type": "FreeTrialPricingTerm", "Duration": "P30D", "Grants": [ { "DimensionKey": "ml.m4.4xlarge.m.i.b" }, { "DimensionKey": "ml.m5.4xlarge.m.i.b" }, { "DimensionKey": "ml.m4.16xlarge.m.i.b" }, { "DimensionKey": "m.i.c" }, { "DimensionKey": "ml.m4.4xlarge.a.t" }, { "DimensionKey": "ml.m5.4xlarge.a.t" }, { "DimensionKey": "ml.m4.16xlarge.a.t" } ] } ] } }, ] } ``` ## Required fields + `Entity` (object) (required) - Contains information about the offer of your ML product. + `Identifier` (string) (required) – The offer id for which you would like to update pricing terms. For more information, see [Identifier](https://docs.aws.amazon.com/marketplace/latest/APIReference/catalog-apis.html#identifier). + `Type` (string) (required) – The `Type` must be `Offer@1.0` for updating pricing. + `DetailsDocument` (object) (required) – Details about the pricing terms of your machine learning product. + `PricingModel` (string) (required) - The pricing model for your product - you can choose between Usage, Free, and Contract (for private offers). For more information, see [Machine Learning Product Pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/machine-learning-pricing.html). + `Terms` (array of objects) - An array of pricing terms that collectively define the overall pricing of your product. + `Type` (string) (required) - The type of pricing term. Valid options are `UsageBasedPricingTerm` or `FreeTrialPricingTerm` or `FixedUpfrontPricingTerm` (for private offers). + `CurrencyCode` (string) (required for `UsageBasedPricingTerm` or `FixedUpfrontPricingTerm` - the currency of the pricing term. Valid values are `USD`. + `RateCards` (array of objects) (required for `UsageBasedPricingTerm`) - The rate cards that define the pricing for your machine learning product. You must include one `RateCard` only within this array. + `RateCard` (array of objects) - The array of dimensions and rates for your machine learning product. All supported instance types must be priced in order to publish your product. + `DimensionKey` - The dimension you are pricing. Valid dimension keys are: + Instance type followed by the operation for hourly rates: + Instance type will start with `ml` followed by the instance name and size. For exampole, `ml.m4.xlarge` + Operation will be `m.i.b` for batch transform, `m.i.r` for hourly real-time inference, and `a.t` for algorithm training. + Examples: `ml.m4.4xlarge.m.i.b` for batch transform, `ml.m4.xlarge.m.i.r` for real-time inference, or `ml.m4.16xlarge.a.t` for algorithm training + `m.i.c` for real-time per inference pricing. + `Price` - The rate of the dimension. The rate is either hourly or per-inference, depending on the dimensionKey. + `Duration` (string) (required for `FreeTrialPricingTerm` or `FixedUpfrontPricingTerm` - The duration of your free trial or contract. For free trial valid values are between X and Y. For contract, valid values are between X and Y. + Grants (array of objects) - Details about which dimensionKeys are eligible for free trial. All supported dimensionKeys must be provided. + DimensionKey - The dimension to include as part of the free trial offer. + Instance type followed by the operation for hourly rates: + Instance type starts with `ml` followed by the instance name and size e.g. `ml.m4.xlarge` + Operation is `m.i.b` for batch transform, `m.i.r` for hourly real-time inference, or `a.t` for algorithm training. + Examples: `ml.m4.4xlarge.m.i.b` for batch transform, `ml.m4.xlarge.m.i.r` for real-time inference, or `ml.m4.16xlarge.a.t` for algorithm training + `m.i.c` for real-time per inference pricing. ## Response syntax A successful request returns: ``` { "ChangeSetId": "example123456789012abcdef", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef" } ``` ## Change set processing The change request enters a processing queue, where it undergoes several steps: 1. Validation: The system checks to ensure all information meets AWS Marketplace guidelines. + Processing time: Few minutes to several hours + For validation errors, see [Change set status and errors](https://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-seller-products.html#seller-product-change-set-errors). 1. Status monitoring: You can check the status of the request two ways. + Via AWS Marketplace Management Portal + Using the `DescribeChangeSet` operation 1. Completion: When approved, the pricing terms are updated. ## Errors **Asynchronous errors** Specific errors for `UpdatePricingTerms` actions can be retrieved using the `DescribeChangeSet` operation after the change set begins processing. For error details and troubleshooting, see [ Change set status and errors](https://docs.aws.amazon.com/marketplace/latest/APIReference/catalog-apis.html#working-with-change-sets). | Error code | Error message | | --- | --- | | INCOMPATIBLE\$1PRODUCT\$1STATUS | Use an existing limited or public product. | # Restrict a version You can use the Catalog API to restrict a version of your machine learning product in AWS Marketplace. When restricted, new buyers cannot access that version. Existing subscribers retain access to restricted versions. AWS Marketplace guidelines require continued support for existing buyers for 90 days after restriction. **Important** At least one unrestricted version must remain available. You cannot restrict the last publicly available version of a product. **To restrict a version:** + To restrict a version, call the `StartChangeSet` operation with the `RestrictDeliveryOptions` change type. ## Request syntax ``` POST /StartChangeSet HTTP/1.1 Content-type: application/json { "Catalog": "AWSMarketplace", "ChangeSet": [ { "ChangeType": "RestrictDeliveryOptions", "Entity": { "Identifier": "example1-abcd-1234-5ef6-7890abcdef12@1", "Type": "MachineLearningProduct@1.0" }, "DetailsDocument": { "DeliveryOptionIds": [ "example1-2222-cccc-2222-cccccccccccc" ] } } ] } ``` ## Required fields **Required fields** + `Entity` (object)—required Contains information about your ML product. + `Identifier` (string)—required Your product ID. For more information, see [Identifier](https://docs.aws.amazon.com/marketplace/latest/APIReference/catalog-apis.html#identifier). + `Type` (string)—required Specifies the delivery method (product type). It must be `MachineLearningProduct@1.0`. + `DetailsDocument` (object)—required Contains the updated version information. + `DeliveryOptionIds` (array of objects)—required List of DeliveryOption IDs for the versions you want to restrict. Retrieve the unique identifier for each DeliveryOption by calling the DescribeEntity action on the version you're restricting. ## Response syntax A successful request returns: ``` { "ChangeSetId": "example123456789012abcdef", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef" } ``` 1. Validation: The system checks if all information meets AWS Marketplace guidelines. + Processing time: Few minutes to several hours + For validation errors, see [Change set status and errors](https://docs.aws.amazon.com/marketplace/latest/APIReference/work-with-seller-products.html#seller-product-change-set-errors). 1. Status monitoring: You can check the status of the request two ways. + Via AWS Marketplace Management Portal + Using the `DescribeChangeSet` operation 1. Completion: When approved, the new version is restricted. ## Errors **Asynchronous errors** The following errors may occur during change set processing and can be retrieved using the `DescribeChangeSet` operation: | Error code | Error message | | --- | --- | | INCOMPATIBLE\$1PRODUCT\$1STATUS | Use an existing public or limited product | | MISSING\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option from existing list of IDs. | | INVALID\$1DELIVERY\$1OPTION\$1IDS | Provide delivery option IDs that can be found in the product. IDs not found: [x] | | INVALID\$1DELIVERY\$1OPTION\$1STATUS | The delivery option IDs [invalid\$1ids] are invalid. Provide delivery options in the public state. | | ALL\$1DELIVERY\$1OPTIONS\$1RESTRICTED | Provide fewer delivery options to restrict as at least one must remain in public state. |