Working with SaaS products - AWS Marketplace Catalog API
Add delivery optionsUpdate delivery optionsUpdate delivery option visibility

Working with SaaS products

You can use the AWS Marketplace Catalog API to automate tasks for working with SaaS-based products.

For information about creating a SaaS-based product using the Catalog API, see Create a product.

The following topics describe how to use the Catalog API to perform actions on your SaaS-based products:

Add delivery options

You can use the Catalog API to add delivery options for a SaaS product in AWS Marketplace.

To add detailed information for delivery options, call the StartChangeSet API operation with the AddDeliveryOptions change type to add delivery details, as shown in the following example.

Note

This is only supported for one delivery option: SaaSUrlDeliveryOptionDetails. It allows you to add the FulfillmentUrl to the SaaS product.

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": "SaaSProduct@1.0"
            },
            "DetailsDocument": {
                "DeliveryOptions": [
                    {
                        "Details": {
                            "SaaSUrlDeliveryOptionDetails": {
                                "FulfillmentUrl": "url to seller's account registration/login page",
                                "QuickLaunchEnabled": true,
                                "LaunchUrl": "URL",
                                "UsageInstructions": "Instructions",
                                "DeploymentTemplates": [
                                    {
                                        "Title": "CloudFormation Template 123",
                                        "Description": "CloudFormation description",
                                        "IamPolicy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:Get*\",\"s3:List*\"],\"Resource\":\n[\"arn:aws:s3:::EXAMPLE-BUCKET\",\"arn:aws:s3:::EXAMPLE-BUCKET/*\"]}]}",
                                        "CloudFormationDetails": {
                                            "TemplateUrl": "URL",
                                            "DefaultStackName": "Name"
                                        }
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Provide information for the fields to add the AddDeliveryOptions change type:

  • Entity (object) (required) – Your SaaS-based product.

    • Identifier (string) (required) – Your product ID. For more information, see Identifier.

    • Type (string) (required) – The Type is based on the delivery method (product type) that your product will be using: SaaSProduct@1.0.

  • DetailsDocument (object) (required) – Details of the request.

    • DeliveryOptions (array) – Details of the delivery options being added.

      • Details (object) – Contains the SaaSUrlDeliveryOptionDetails of a delivery option to be added.

        • SaaSUrlDeliveryOptionDetails (object) – Contains the FulfillmentUrl of a delivery option for SaaS product.

          • FulfillmentUrl (string) – The URL to be added to the SaaS product.

        • QuickLaunchEnabled (boolean) – Determines if buyers can use Quick Launch to configure and launch the software. The default value is FALSE.

        • LaunchUrl (string) – The URL to your SaaS product’s landing page. This is required if QuickLaunchEnabled is set to True.

        • DeploymentTemplates (array) – Deployment templates that customers can use to set up and configure the SaaS product and any related AWS resources.

          • Title (string) – The display name of the deployment template.

          • Description (string) – A description for what the deployment template contains.

          • IamPolicy (string) – An IAM policy describing the permissions needed to deploy the template. Buyers can use this IAM policy to quickly deploy the template.

          • CloudFormationDetails (object) – The details of a AWS CloudFormation template.

            • TemplateUrl (string) – The URL for the deployment template.

              Note

              For support obtaining your CloudFormation template URL, contact your AWS Marketplace business development partner or the AWS Marketplace Seller Operations team.

            • DefaultStackName (string) – The default name used in CloudFormation when the seller creates the stack.

      • UsageInstructions (string) – (Optional) Instructions for using this delivery option. Include documentation for manual steps for customers who won’t use DeploymentTemplates.

Response Syntax

A change set is created for your request. The response to this request gives you the ID for the change set and looks like the following.

{
"ChangeSetId": "example123456789012abcdef", 
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-
1:123456789012:AWSMarketplace/ChangeSet/example123456789012abcdef"
}

Synchronous Validations

Error condition Message HTTP code
Invalid Fulfillment Url Provide a valid fulfillment URL beginning with "https://". 422
Multiple URL Delivery Options You provided more than one URL delivery option. Provide one URL delivery option. 422
Invalid Delivery Option Types You provided invalid delivery option details. You must provide a valid parameter for SaaSUrlDeliveryOptionDetails. 422
Invalid Launch URL Provide a valid launch URL beginning with "https://". 422
Missing Launch Url Required parameter LaunchUrl is missing. You must provide a LaunchUrl. 422
Missing deployment templates The deployment template is missing. Provide at least one deployment template. 422
Too many deployment templates You cannot provide more than 20 deployment templates. 422
Invalid template URL Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x] 422
Invalid deployment template stack name The deployment template stack name is invalid. Provide a valid stack name using only alphanumeric characters and hyphens. It must start with an alphabetical character and can't be longer than 128 characters. 422
Duplicate deployment template title You provided duplicate deployment template titles. Provide unique deployment template titles. 422
Duplicate deployment template URL You provided duplicate deployment template urls. Provide unique deployment template urls. 422
Invalid deployment template type The deployment template type is invalid. Provide a valid deployment template type. Supported values are ["CloudFormation@1.0"]. 422
Invalid deployment template IAM policy The deployment template IAM policy is invalid. Provide a valid IAM policy. 422
Invalid usage instructions

  • Images aren't supported by the usage instructions. Remove the image [x].

  • You provided a link to an invalid URL in the usage instructions: [x]. Provide a valid URL.

  • You provided a link with an unsupported URI scheme in the usage instructions. Use a supported scheme: ["http", "https", "tel", "mailto"].

 422

Asynchronous Errors

Error code Error message
DUPLICATE_DELIVERY_OPTIONS You provided one or more delivery option types that already exist for this product. Provide a unique delivery option type or use UpdateDeliveryOptions if you intended to change an existing delivery option.
INVALID_FULFILLMENT_URL The URL you provided returned HTTP status code [x]. Provide a fulfillment URL that renders with a 200.
INVALID_LAUNCH_URL The URL you provided returned HTTP status code [x]. Provide a launch URL that renders with a 200.
INVALID_TEMPLATE_URL Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x]

Update delivery options

You can use the Catalog API to update the delivery options for a SaaS product in AWS Marketplace.

To update the delivery options, call the StartChangeSet API operation with the UpdateDeliveryOptions change type, as shown in the following example.

Note

This is only supported for one delivery option: SaaSUrlDeliveryOptionDetails. It allows you to update the FulfillmentUrl.

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": "SaaSProduct@1.0"
            },
            "DetailsDocument": {
                "DeliveryOptions": [
                    {
                        "Id": "do-1234567891234567891234",
                        "Details": {
                            "SaaSUrlDeliveryOptionDetails": {
                                "FulfillmentUrl": "https://www.aws.amazon.com/marketplace/management",
                                "LaunchUrl": "URL",
                                "UsageInstructions": "Instructions",
                                "DeploymentTemplates": [
                                    {
                                        "Title": "CloudFormation Template 123",
                                        "Description": "CloudFormation description",
                                        "IamPolicy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:Get*\",\"s3:List*\"],\"Resource\":\n[\"arn:aws:s3:::EXAMPLE-BUCKET\",\"arn:aws:s3:::EXAMPLE-BUCKET/*\"]}]}"
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Provide information for the fields to add the AddDeliveryOptions change type:

  • Entity (object) (required) – Your SaaS-based product.

    • Identifier (string) (required) – Your product ID. For more information, see Identifier.

    • Type (string) (required) – The Type is based on the delivery method (product type) that your product will be using: SaaSProduct@1.0.

  • DetailsDocument (object) (required) – Details of the request.

    • DeliveryOptions (array) – Contains the details of the delivery options being updated.

      • Id (string) – Unique identifier for the DeliveryOption. (Get the unique identifier for the DeliveryOption by calling the DescribeEntity action on the product you are updating.)

      • Details (object) – Contains the SaaSUrlDeliveryOptionDetails of the delivery option to be updated.

        • SaaSUrlDeliveryOptionDetails (object) – Contains the FulfillmentUrl of a delivery option for SaaS product.

          • FulfillmentUrl (string) – The URL to be updated for the SaaS product.

          • LaunchUrl (string) – The URL to your SaaS product’s landing page. This is required if QuickLaunchEnabled is set to True.

          • UsageInstructions (string) – Instructions for using this delivery option. Include documentation for manual steps for customers who won’t use DeploymentTemplates.

          • DeploymentTemplates (array) – Deployment templates that customers can use to set up and configure the SaaS product and any related AWS resources.

            • Title (string) – The display name of the deployment template.

            • Description (string) – A description for what the deployment template contains.

            • IamPolicy (string) – An IAM policy describing the permissions needed to deploy the template. Buyers can use this IAM policy to quickly deploy the template.

            • CloudFormationDetails (object) – The details of a CloudFormation template.

              • TemplateUrl (string) – The URL for the deployment template.

              • DefaultStackName (string) – The default name used in AWS CloudFormation when the customer is creating the template.

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 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

Error condition Message HTTP code
Empty Delivery Option Ids Provided Details is not valid. String '' at /DeliveryOptions/0/Id does not match required schema regex, '^do-[a-zA-Z0-9]+$' 422
Missing Delivery Option Ids Provided Details is not valid. JSON at /DeliveryOptions/0 is missing required properties: ['Id']. 422
Duplicate Delivery Option Ids Provide unique delivery option IDs. 422
Invalid Fulfillment Url Provide a valid fulfillment URL beginning with "https://". 422
Invalid Delivery Option IDs Provide delivery option IDs that can be found in the product. IDs not found: [x] 422
Multiple URL Delivery Options You provided more than one URL delivery option. Provide one URL delivery option. 422
Missing delivery option ids The delivery option ID is missing. Provide one or more valid delivery option IDs that you wish to update, or use AddDeliveryOptions if you intended to add a new delivery option. 422
Invalid Launch URL Provide a valid launch URL beginning with "https://". 422
Missing Launch Url Required parameter LaunchUrl is missing. You must provide a LaunchUrl. 422
Missing deployment templates The deployment template is missing. Provide at least one deployment template. 422
Too many deployment templates You cannot provide more than 20 deployment templates. 422
Invalid template URL Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x] 422
Invalid deployment template stack name The deployment template stack name is invalid. Provide a valid stack name using only alphanumeric characters and hyphens. It must start with an alphabetical character and can't be longer than 128 characters. 422
Duplicate deployment template title You provided duplicate deployment template titles. Provide unique deployment template titles. 422
Duplicate deployment template URL You provided duplicate deployment template urls. Provide unique deployment template urls. 422
Invalid deployment template type The deployment template type is invalid. Provide a valid deployment template type. Supported values are ["CloudFormation@1.0"]. 422
Invalid deployment template IAM policy The deployment template IAM policy is invalid. Provide a valid IAM policy. 422
Invalid usage instructions

  • Images aren't supported by the usage instructions. Remove the image [x].

  • You provided a link to an invalid URL in the usage instructions: [x]. Provide a valid URL.

  • You provided a link with an unsupported URI scheme in the usage instructions. Use a supported scheme: ["http", "https", "tel", "mailto"].

 422

Asynchronous Errors

Error code Error message
INVALID_DELIVERY_OPTION_IDS Provide delivery option IDs that can be found in the product. IDs not found: [x]
AUDIT_ERROR AWS MP Catalog Audits List - CQ team
INVALID_FULFILLMENT_URL The URL you provided returned HTTP status code [x]. Provide a fulfillment URL that renders with a 200.
INVALID_LAUNCH_URL The URL you provided returned HTTP status code [x]. Provide a launch URL that renders with a 200.
INVALID_TEMPLATE_URL Quick Start URL is invalid. Provide deployment template URL that is published through AWS QuickStarts to Amazon S3. Invalid deployment templates URL: [x]

Update delivery option visibility

You can use the Catalog API to configure permissions so that only some users can change the visibility for a SaaS product in AWS Marketplace.

To configure permissions so that only some users can change the visibility for a SaaS product, call the StartChangeSet API operation with the UpdateDeliveryOptionsVisibility change type, as shown in the following example.

Note

This is only supported for one delivery option: SaaSUrlDeliveryOptionDetails.

Request Syntax

POST /StartChangeSet HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateDeliveryOptionsVisibility",
      "Entity":
      {
        "Identifier": "prod-example12345",
        "Type": "SaaSProduct@1.0"
      },
      "DetailsDocument":
      {
        "DeliveryOptions":
        [
          {
            "Id": "do-1234567891234567891234",
            "TargetVisibility": "Public"
          },
          {
            "Id": "do-43210987654321",
            "TargetVisibility": "Limited",
            "Targeting":
            {
              "PositiveTargeting":
              {
                "BuyerAccounts":
                [
                  "123456789012"
                ]
              }
            }
          }
        ]
      }
    }
  ]
}

Provide information for the fields to add the UpdateDeliveryOptionsVisibility change type:

  • Entity (object) (required) – Your SaaS-based product.

    • Identifier (string) (required) – Your product ID. For more information, see Identifier.

    • Type (string) (required) – The Type is based on the delivery method (product type) that your product will be using: SaaSProduct@1.0.

  • DetailsDocument (object) (required) – Details of the request.

    • DeliveryOptions (array) – List of DeliveryOptions to be updated.

      • Id (string) – The delivery option id to be updated.

      • TargetVisibility (string) – The intended new visibility of the delivery option.

        Possible values: Limited, Public, and Unavailable.

        Note

        There is always exactly one Public delivery option, and a maximum of one Limited delivery option.

      • Targeting (object) optional – Targeting of the delivery option, used in conjunction with the Limited visibility status to be able to test the new delivery option before changing the visibility to Public.

        • PositiveTargeting (object) – Specifying inclusive targeting.

          • BuyerAccounts (array of strings) – The list of buyer AWS account ids who will be able to use the new delivery option.

            Min size: 0. Max size: 100.

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 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 in the Catalog API with the DescribeChangeSet action.

Synchronous Validations

Error condition Message HTTP code
Missing delivery option ids The delivery option ID is missing. Provide one or more valid delivery option IDs that you wish to update, or use AddDeliveryOptions if you intended to add a new delivery option. 422
Invalid visibility You provided invalid option for TargetVisibility. Allowed options are: Limited, Public, Unavailable. 422
Invalid targeting You provided invalid option for PositiveTargeting. You must provide a valid parameter for BuyerAccounts. 422
Missing Visibility and Targeting You provided invalid delivery option visibility details. You must provide a valid parameter for at least one of TargetVisibility or Targeting. 422
Too many AWS account ids You cannot provide more than 100 targeted buyer accounts. 422

Asynchronous Errors

Error code Error message
INVALID_DELIVERY_OPTION_IDS You provided invalid delivery option details. Provide delivery option IDs that can be found in the product. IDs not found: [x]
INVALID_VISIBILITY You provided more than one delivery option for the pubic state. Provide only one public delivery option.
INVALID_VISIBILITY You didn't provide a public delivery option. Provide one public delivery option.
AUDIT_ERROR Varies based on MCO manual review.