Automate Discounts with AWS Marketplace Catalog API to Streamline Sales

This post discusses how AWS Marketplace sellers can leverage the AWS Marketplace Catalog API to streamline the creation of promotions through Private Offers. We provide a detailed guide on using the Catalog API to generate Private Offers, incorporating specific buyer information obtained from your website. This approach streamlines creating discounts, resulting in more efficient transactions and an improved buyer experience in AWS Marketplace.

Prerequisites

To follow along with the samples in this post, you need:

An AWS account registered as a seller in AWS Marketplace.
An existing paid product published in AWS Marketplace, publicly available to all buyers.
The following AWS Identity and Access Management (IAM) policy permissions in your AWS account:
- - AWSCloudShellFullAccess to use a broser-based shell.
  - AWSMarketplaceSellerFullAccess to submit offers for publishing.
Basic understanding of JSON and Python programming languages.

Note: The commands for setting the prices and sharing the private offer link vary depending on Marketplace product types (AMI, Container, SaaS). In our scenario, we will extend a private offer for a SaaS product with a Subscription.

Solution overview

The AWS Marketplace Private Offer feature enables you to create custom pricing and terms negotiated with your customers, in addition to the publicly available offerings. This provides flexibility in pricing and licensing agreements, making it easier to meet the specific needs of your buyers.You can automate the direct extension of private offers using the AWS Marketplace Catalog API.

However, for this blog article,we’ll explore how to leverage the AWS Marketplace Catalog API to automate the extension of private offers, focusing on providing promotional discounts. Instead of manually creating private offers through the seller portal for each request, this method streamlines the process, allowing for efficient and seamless delivery of discounts to buyers in alignment with your promotional strategies.

This automation brings significant benefits including:

Efficiency: Automating the creation of private offers via API streamlines the extension of private offer based on preset rules and conditions.
Scalability: You can easily manage many offers, making it feasible to handle high-volume periods without being overwhelmed by administrative tasks.
Consistency: Automated processes ensure that all offers are handled uniformly, reducing the risk of errors and inconsistencies that can occur with manual negotiations.
Enhanced Buyer Experience: Buyers receive timely and accurate private offers, improving their overall experience and increasing the likelihood of conversion.

By leveraging the AWS Marketplace Catalog API, sellers can efficiently cater to the specific needs of their buyers, offering tailored solutions quickly and effectively:

Figure 1: Solution overview

Buyer visits seller’s website: The journey begins when a potential buyer lands on your website to explore the offerings.
Buyer submits AWS account ID and email: Your website implements a verification process to ensure the buyer meets specific eligibility criteria for the private offer.
Seller’s site verifies buyer’s eligibility: Upon passing the eligibility check, the buyer is prompted to submit their AWS account ID and email address, which are crucial for the subsequent steps.
Seller’s application calls AWS Catalog API to create and send the private offer: Using the provided AWS account ID and email, your application interacts with the AWS Catalog API to generate a tailored private offer for the buyer. Once the private offer is created, you email it to the buyer.
Buyer accesses the offer and sees the discounted offer: The final step involves the buyer clicking on the private offer link received via email. This redirects them to the AWS Marketplace, where they can view and accept the offer, including the negotiated discounts and payment terms.

Private offer creation steps:

Ensure you are logged in with the appropriate seller account and follow these steps to create a private offer using the AWS Marketplace Catalog API.

Log in to your AWS Console and access the AWS Management Console.
Open AWS CloudShell. If this is your first time using CloudShell, Close the Welcome to AWS CloudShell dialog and wait until AWS CloudShell is ready.

Figure 2: AWS Console Cloudshell

AWS CloudShell is a browser-based shell environment from Amazon Web Services (AWS) that allows users to manage AWS resources directly from a web browser. It includes pre-installed command-line tools like the AWS CLI and SDKs, eliminating the need for local setup. Users have 1 GB of persistent storage for scripts and configurations across sessions. Accessed via a web browser, CloudShell requires no additional software and is secure, adhering to the user’s IAM permissions. It integrates seamlessly with AWS services for managing resources like EC2 instances and S3 buckets.

Set the variables needed to create the private offer: Replace the placeholder values with your actual Marketplace product ID, buyer’s AWS account ID, and offer validity dates.

# Set info for draft private offer 
export PRODUCT_ID=prod-example12345
export BUYER_ID=123456789012
export EXPIRY_DATE=YYYY-MM-DD # Example: 2023-12-12 export SELLER_ID="$(aws sts get-caller-identity --query 'Account' --output text;)";

Create a JSON Payload with the by running the following command:

cat << EOF > create_draft_input.json
{
    "Catalog": "AWSMarketplace",
    "ChangeSet": [{
            "ChangeName": "MyCreateOfferChange",
            "ChangeType": "CreateOffer",
            "Entity": {
                "Type": "Offer@1.0"
            },
            "DetailsDocument": {
                "ProductId": "$PRODUCT_ID"
            }
        },
        {
            "ChangeType": "UpdateInformation",
            "Entity": {
                "Type": "Offer@1.0",
                "Identifier": "\$MyCreateOfferChange.Entity.Identifier"
            },
            "DetailsDocument": {
                "Name": "Demo Private Offer",
                "Description": "Demo Private Offer Description"
            }
        },
        {
            "ChangeType": "UpdateTargeting",
            "Entity": {
                "Type": "Offer@1.0",
                "Identifier": "\$MyCreateOfferChange.Entity.Identifier"
            },
            "DetailsDocument": {
                "PositiveTargeting": {
                    "BuyerAccounts": [
                        "$BUYER_ID",
                        "$SELLER_ID"
                    ]
                }
            }
        },
        {
            "ChangeType": "UpdateAvailability",
            "Entity": {
                "Type": "Offer@1.0",
                "Identifier": "\$MyCreateOfferChange.Entity.Identifier"
            },
            "DetailsDocument": {
                "AvailabilityEndDate": "$EXPIRY_DATE"
            }
        },
        {
            "ChangeType": "UpdateLegalTerms",
            "Entity": {
                "Identifier": "\$MyCreateOfferChange.Entity.Identifier",
                "Type": "Offer@1.0"
            },
            "DetailsDocument": {
                "Terms": [{
                    "Type": "LegalTerm",
                    "Documents": [{
                        "Type": "StandardEula",
                        "Version": "2022-07-14"
                    }]
                }]
            }
        }
    ]
}
EOF

Create the Draft Private Offer using the following command:

aws marketplace-catalog start-change-set \ 
--region us-east-1 \ 
--cli-input-json file://create_draft_input.json

Wait 1-2 minutes and re-run the DescribeChangeSet action command until the status shows SUCCEEDED.

Note: Amazon EventBridge can automate notifications and actions related to changes in your AWS Marketplace offers, ensuring you stay updated with the latest statuses and events. This powerful feature allows seamless integration with various AWS services and can enhance your workflow.

Capture the offer ID from the response and set it as a variable for future steps.
Replace the offer ID with your offer ID and run it to set it to a variable.

export OFFER_ID="offer-example12345"

In this section, we set a price for the private offer for a SaaS product with the “Subscription” pricing model. You need to create a payload that works with your product type and pricing model. See the AWS Marketplace seller workshop for examples of other product types and pricing models. In our following example, we use P100D for 100 days for this contract. We set custom prices for each of the 3 usage dimensions.

export USAGE_DURATION_DAYS="P100D"

Replace the JSON array of objects in the RateCard in the following command to include all usage dimensions in your product. For each usage dimension, set the Price property to the per-unit price. Then run the command to create the payload.

cat << EOF > update_draft_input.json
{
    "Catalog": "AWSMarketplace",
    "ChangeSet": [{
            "ChangeType": "UpdatePricingTerms",
            "Entity": {
                "Type": "Offer@1.0",
                "Identifier": "$OFFER_ID"
            },
            "DetailsDocument": {
                "PricingModel": "Usage",
                "Terms": [{
                    "Type": "UsageBasedPricingTerm",
                    "CurrencyCode": "USD",
                    "RateCards": [{
                        "RateCard": [{
                            "DimensionKey": "metered_1_id",
                            "Price": "0.001"
                        }, {
                            "DimensionKey": "metered_2_id",
                            "Price": "0.001"
                        }, {
                            "DimensionKey": "metered_3_id",
                            "Price": "0.001"
                        }]
                    }]
                }]
            }
        },
        {
            "ChangeType": "UpdateValidityTerms",
            "Entity": {
                "Type": "Offer@1.0",
                "Identifier": "$OFFER_ID"
            },
            "DetailsDocument": {
                "Terms": [{
                    "Type": "ValidityTerm",
                    "AgreementDuration": "$USAGE_DURATION_DAYS"
                }]
            }
        }
    ]
}
EOF

Run the following command to set the prices of your draft private offer using the StartChangeSet action.

aws marketplace-catalog start-change-set \
 --region us-east-1 \
--cli-input-json file://update_draft_input.json

Replace the change_set_id in the following command with the change set ID from the previous command’s output and run it to view the status.

aws marketplace-catalog describe-change-set \ 
--region us-east-1 \ --catalog "AWSMarketplace" \ 
--change-set-id "example_change_set_id";

Run the following command to make the Private Offer available to the buyer:

aws marketplace-catalog start-change-set \
  --region us-east-1 \
  --catalog AWSMarketplace \
  --change-set '[
    {
      "ChangeType": "ReleaseOffer",
      "DetailsDocument": {},
      "Entity": {
        "Identifier": "'"${OFFER_ID}"'",
        "Type": "Offer@1.0"
      }
    }
  ]';

Wait 5-10 minutes and re-run the DescribeChangeSet action command until the status shows SUCCEEDED. Refer to the provided Amazon EventBridge documentation to programmatically check for change set statuses and offers.
```
aws marketplace-catalog describe-change-set \
 --region us-east-1 \
 --catalog "AWSMarketplace" \
 --change-set-id "example_change_set_id";
```

To view the private offer created in the previous task, use the following DescribeEntity action:

aws marketplace-catalog describe-entity \
 --region us-east-1 \
 --catalog AWSMarketplace \
 --entity-id "${OFFER_ID}";

You can also view the private offer on the Offers page in the seller portal. Search for the new offer ID and select it to view details:

Figure 3: AWS Sellers Private offers dashboard

Create a Link for Buyers to View and Accept the Offer

Echo
"https://aws.amazon.com/marketplace/saas/ordering?productId=${PRODUCT_ID}&offerId=${OFFER_ID}"

Once the offer is created, AWS Marketplace sends an email notification to the email address registered with the buyer’s AWS account , you can also share the URL directly through email. The creation and availability of the offer take a few minutes to a few hours. Buyers can review and accept the offer by clicking the provided link, signing in with their AWS account, and confirming the purchase under the specified terms. Additionally, sellers can use Amazon EventBridge to receive notifications about the status of their private offers, ensuring they stay informed about offer views, acceptances, and any changes.

Conclusion:

This automation capability significantly enhances your operational efficiency in creating Private Offers by allowing you to streamline the creation of discounts for your multiple promotions. This underscoring the transformative impact of the AWS Marketplace Catalog API on the private offer creation process.

For more details on programmatically creating private offers for additional Marketplace product types, visit the AWS Marketplace Seller Workshop.

Additionally, you can use Amazon EventBridge notifications to programmatically check for change set statuses and offers:

About the author

Author's Portrait
Elhadj Barry is a DC-based Marketplace Specialist Solutions Architect with a focus on AWS Marketplace Governance and Security. He is passionate about utilizing AWS services to create innovative solutions that drive value and business outcomes.