AWS Marketplace
Automate the pricing of your AWS Marketplace resources with Catalog API
Amazon Web Services (AWS) recently announced the public launch of new features within the AWS Marketplace Catalog APIs. These features will help you programmatically manage additional characteristics of your products, offers, resale authorizations, and Channel Partner Private Offers (CPPO).
As an experienced seller, you are familiar with managing the pricing models, dimensions, and related updates via the user interface in the seller portal. Now, the ability to perform these tasks using an API lets you automate repetitive functions and streamline offer management.
In AWS Marketplace, pricing models are designed to provide flexibility for sellers and choice for customers. This lets customers select a product that is closest to their utilization patterns and budget considerations. You can configure dimensions and pricing models to meet your business requirements. This applies for all product types, such as Amazon Machine Image (AMI), container, or SaaS that you can offer via AWS Marketplace.
This post will provide an overview of how you can take advantage of APIs to manage pricing aspects of your products, offers, resale authorizations, and CPPOs. You will learn about pricing terms and how to update them programmatically using the AWS Marketplace Catalog API.
Pricing-related changes
To make changes using the AWS Marketplace Catalog API, you use the StartChangeSet action. In the request payload, you include a change type and an entity that the change applies to.
The following list shows the different types of pricing-related changes that you can make. For each type, the available change types and the applicable entity types are included. You will use multiple change types to create a product and set a price. For example, in this post, we add an EC2 instance type to an AMI product as a dimension using the AddDimensions ChangeType in StartChangeSet action. Then using the API for offers, you can use the UpdatePricingTerms and UpdatePaymentScheduleTerms change types to manage the pricing aspects of the product.
Note: For a full list of actions supported under each operation, review the documentation for details.
- Create dimensions for a product – Entity Type(s):
AmiProduct,ContainerProduct, orSaaSProduct. Pricing specific Change type: AddDimensions - Set prices for dimensions – Entity Types: Offer. Pricing specific Change type(s):
UpdatePricingTermsorUpdatePaymentScheduleTerms - Authorize resellers – Entity Type(s): ResaleAuthorization. Pricing specific Change type(s):
UpdatePricingTermsorUpdatePaymentScheduleTerms - Set prices for dimensions as a reseller (a channel partner) – Entity Type(s): Offer (A valid ResaleAuthorizationId is a pre-requisite for resellers). Pricing specific Change type(s):
UpdateMarkup,UpdatePricingTerms, orUpdatePaymentScheduleTerms
For each change type (such as UpdatePricingTerms or UpdatePaymentScheduleTerms), you must pass additional information, such as pricing model, terms, or dimensions. Review the documentation for UpdatePricingTerms and UpdatePaymentScheduleTerms for details.
Solution overview
AWS Marketplace seller labs are available to help you quickly identify the attributes that you should provide in the API request payload. This includes how to set up different pricing models, create offers, or authorize resellers. In this post, a sample product configuration is provided for an AMI Product. The example shows a pricing based on hourly usage, with annual upfront payment, and a flexible payment schedule. The following is an example of attributes needed for the API request load.
- Product Type – AMI
- Create dimensions –
AddDimensionschange type - Set prices –
UpdatePricingTermsandUpdatePaymentScheduleTermschange types
Pricing models in AWS Marketplace
Here is a quick summary of pricing models and related terminology in the context of AWS Marketplace:
Pricing Models
Hourly pricing – You set an hourly price per EC2 instance. Each instance type can be priced differently. Charges are based on the number of EC2 instances that the buyer deploys and the number of hours they run. Usage is rounded up to the nearest whole hour per instance.
Monthly pricing – You set a fixed monthly price, regardless of the number of EC2 instances the buyer runs. Monthly charges are pro-rated at sign-up and upon cancellation. Example: A buyer who subscribes for one day in the month of November is charged for 1/30th of the month.
Annual pricing – An annual pricing model enables sellers to offer products to customers who can purchase a 12-month subscription. The customer is invoiced for the full amount of the contract at the time of subscription. Note that for some pricing models, the annual pricing is optional for the buyer. This means that the buyer can choose to pay by the hour instead of the annual price.
Usage pricing – Also known as “pay as you go” pricing, customers only pay for what they use. As a seller, you choose from one of the following categories: users, hosts, bandwidth, data, tiers, or units (for custom categories). You can set up to 24 different pricing categories called dimensions. The customer specifies the quantity that they would like to purchase for each dimension. The charges are measured and reported using pricing dimensions when the API is invoked by the software.
Contract pricing – Sellers can offer upfront pricing to customers that lets them buy a license for 1 month, 12 months, 24 months, or 36 months.
Bring Your Own License (BYOL) pricing – All BYOL products must be accompanied by a paid version available for purchase in AWS Marketplace. However, there is a 90 days grace period from the launch of your BYOL product. After 90 days, a paid version of your product must be made available.
Terminology
Pricing Dimension – A pricing dimension is a unit of measure that sellers define for charging buyers. Sellers must configure this information to bill buyers for using the product, whether it is an annual, usage-based, or contract-based pricing model.
Offer – An offer has a collection of terms to be accepted for an agreement between the seller and buyer. The accepted terms from the offer are translated into an agreement as proof of the transaction. An offer can be public or private.
- Public offers are a globally discoverable purchasing program. Sellers can specify targeting based on programs and geographical location. This makes the offer accessible to a specific set of customers based on the given criteria.
- Private offers let sellers and buyers negotiate custom prices and end user license agreement (EULA) terms for software purchases in AWS Marketplace.
Agreement – Agreements are created as the result of an accepted offer. Review the Agreements API documentation to learn more.
Pricing terms – A collection of options within an agreement. Based on the pricing model, the pricing terms can be one or more combinations of term types. For an example of this, see section B showing how to set an AMI pricing model to hourly with annual pricing.
The following diagram depicts the components of pricing terms.
Figure 1 – Components of pricing terms
Flexible payment schedules: Flexible payment schedules let sellers extend private offers with a custom payment schedule. The schedule can be spread over a period of up to five years. Seller can set the amount and date of invoice on which the customer gets the invoice for payment. For example, a payment schedule can invoice the customer $1000 on January 15, $100 on February 1, and $100 on March 30 for a one-year subscription.
Solution Walkthrough: Use API to manage pricing for AWS Marketplace resources
Prerequisites
The following prerequisites are required to manage pricing configurations using the AWS Marketplace Catalog APIs:
- You understand how AWS Marketplace Pricing features work.
- You have necessary permissions to run AWS Marketplace Catalog API.
- You must have access to AWS Marketplace Management Portal (AMMP).
- Your AWS account must be fully registered with AWS Marketplace as a seller. For details on how to register, see the Checklist to successfully registering as a seller in AWS Marketplace.
- You have selected your product and pricing model based on your business goals.
- You understand general AWS Marketplace Catalog API concepts, such as: Entity, ChangeType, StartChangeSet action, ListEntities action, DescribeEntity actions. You know how to use these programmatically.
Code Examples
In the following sections, we will show a few examples of how to create pricing terms for an AMI based product. We will be using AWS Marketplace Catalog API StartChangeSet action with the UpdatePricingTerms change type.
The AWS Marketplace Catalog API StartChangeSet action lets you request changes for your products, offers, resale authorizations, and CPPO. We will use the StartChangeSet action to: (a) add a pricing dimension, (b) update the pricing and (c) create payment schedules for the AMI product and offer. Once the StartChangeSet action is initiated, the response returns a ChangeSetId for tracking purposes. You can check the status of the request through AMMP, or in the API with the DescribeChangeSet action.
Note: The following examples contain the section of StartChangeSet action request message specific to pricing scenarios only. These examples are related to AMI product but the same approach applies to SaaS and container products as well. You may combine all the different change type request in this blog into one single StartChangeSet call. Review the documentation to understand the request syntax for each action. All code examples shown in this post can be found in the AWS Marketplace Reference Code Library.
A. Adding pricing dimensions for AMI product
In this example, we add an EC2 instance type to an AMI product as a metered dimension. This makes the instance type available for buyers to launch your AMI on. Subsequent sections show various options of building on top of this example.
The StartChangeSet action with the AddDimensions change type applies a billable pricing unit of measure on products that will be used to charge users. The AddDimensions change type adds a pricing dimension to a product.
{
"ChangeType": "AddDimensions",
"Entity": {
"Identifier": "prod-1111111111111",
"Type": "AmiProduct@1.0"
},
"DetailsDocument": [
{
"Key": "t2.micro",
"Description": "Dimension for t2.micro instance type.",
"Name": "t2.micro",
"Types": [
"Metered"
],
"Unit": "Hrs"
},
{
"Key": "t3.micro",
"Description": " Dimension for t3.micro instance type.",
"Name": "t3.micro",
"Types": [
"Metered"
],
"Unit": "Hrs"
}
]
}
The response from the StartChangeSet action will contain the change set ID. The change set ID can be used to describe the change request and its latest status. In the next step, you will learn how to combine the different pricing terms in the request message.
B. Set pricing for an AMI product with hourly annual pricing model
In the following example, the UsageBasedPricingTerm is used to define the hourly pricing. The ConfigurableUpfrontPricingTerm with duration of 365 days defines an additional annual component that the buyer can prepay which may cost less than the hourly price over the year.
AWS Marketplace API lets you update pricing terms using the StartChangeSet action and the UpdatePricingTerms change type. The UpdatePricingTerms replaces the existing pricing terms in its entirety. The pricing terms that are not included in the latest request will be removed from the offer. A rate card is used to define the per-unit rates for the product dimensions.
The MultipleDimensionSelection constraint determines if buyers are allowed to select multiple dimensions in the rate card. The QuantityConfiguration constraint determines if acceptors are allowed to configure quantity for each dimension in rate card.
The duration is represented using ISO 8601 International standard. In this example, P365D represents duration of 365 days.
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"PricingModel": "Usage",
"Terms": [
{
"Type": "UsageBasedPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"RateCard": [
{
"DimensionKey": "t2.micro",
"Price": "0.17"
}
]
}
]
},
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P365D"
},
"RateCard": [
{
"DimensionKey": "t2.micro",
"Price": "220.00"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
}
]
}
}
In the next example, you will learn how to set the pricing terms for configurable contract pricing in the request message.
c. Set pricing for an AMI product with configurable contract pricing model
In this example, the UpdatePricingTerms change type is being used for the AMI product to set a configurable contract pricing for 12 months. The pricing model is “Contract” and the ConfigurableUpfrontPricingTerm change type is used to define the configurable contract pricing model. A configurable dimension lets a buyer set the number of units they would like to pay for upfront when they subscribe. There is no way for the seller to set a minimum or a maximum number of units. For a buyer to subscribe to this pricing model, at least 1 dimension must be set to a number greater than 0.
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"PricingModel": "Contract",
"Terms": [
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P12M"
},
"RateCard": [
{
"DimensionKey": "t3.micro",
"Price": "220.00"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
}
]
}
}
In the next example, the fixed contract pricing model is used in the request message.
D. Set pricing for an AMI product with fixed contract pricing model
In this example, a buyer selects one of the predefined contract-based pricing tiers from FixedUpfrontPricingTerm. The StartChangeSet action with the UpdatePricingTerms change type can be used to define a fixed contract pricing model, as shown in the following example.
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"PricingModel": "Contract",
"Terms": [
{
"Type": "FixedUpfrontPricingTerm",
"CurrencyCode": "USD",
"Price": "0.0",
"Grants": [
{
"DimensionKey": "t2.micro",
"MaxQuantity": 1
},
{
"DimensionKey": "t3.micro",
"MaxQuantity": 1
}
]
}
]
}
}
In the next example, you will learn how to set the pricing term for free trial pricing model.
E. Set pricing for an AMI product with free trial pricing model
In this example, free trial pricing for a duration of 21 days is set. A FreeTrialPricingTerm change type is used to define a free trial pricing model for the product. This lets customers use a product for a limited period of time without any fee. During this period, the customer can learn about the product and discover value before actually paying for the product.
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"PricingModel": "Usage",
"Terms": [
{
"Type": "FreeTrialPricingTerm",
"Duration": "P21D",
"Grants": [
{
"DimensionKey": "t2.micro"
},
{
"DimensionKey": "t3.micro"
}
]
}
]
}
}F. Set pricing for an AMI product with private offer without flexible payment schedule
In this example, a private offer is created without a flexible payment schedule. Note that the UpdatePaymentScheduleTerms will not be initiated.
Private offers are a purchasing program that let sellers and buyers negotiate custom prices and EULA terms for software purchases in AWS Marketplace. Private offers can be created programmatically for products and target specific buyers with negotiated pricing. When you create a private offer, you can extend the offer to up to 25 accounts. The offer is visible only to the accounts that you create the offer for. Buyers can view the offer once you extend the offer to either their linked account or to their management account.
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"PricingModel": "Contract",
"Terms": [
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P12M"
},
"RateCard": [
{
"DimensionKey": "t3.micro",
"Price": "220.00"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
}
]
}
}In the next example, you will learn how to set pricing term with flexible payment schedule.
G. Set pricing for an AMI product with private offer with flexible payment schedule
In this example, a flexible payment schedule is set for a private offer on an AMI product.
A flexible payment schedule defines an installment-based pricing model where customers are charged a fixed price on different dates during the agreement validity period. The schedule can be spread over a period of five years, and the customer makes payments in installments defined by the schedule. When the buyer accepts this private offer, they will be invoiced according to the payment schedule. In return, they will be entitled to consume what is defined in the pricing dimension. For example, if this is an AMI contract pricing model, the seller can define the number of units of each dimension that is available to the buyer for purchase.
An AWS Marketplace Catalog API action StartChangeSet action implements an UpdatePaymentScheduleTerms change type that can define the payment schedule during different dates.
{
"ChangeType": "UpdatePaymentScheduleTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"Terms": [
{
"Type": "PaymentScheduleTerm",
"CurrencyCode": "USD",
"Schedule": [
{
"ChargeDate": "2024-01-01",
"ChargeAmount": "200.00"
},
{
"ChargeDate": "2024-02-01",
"ChargeAmount": "170.00"
}
]
}
]
}
}In the next section, you will learn how to set the complete request message for AMI product with contract pricing and private offer.
H. Set contract based pricing for an AMI product in a private offer
In this example, a private offer with contract pricing terms for AMI product is created with complete request message to StartChangeSet action. The private offer is targeted for specific buyer accounts (listed under UpdateTargeting ChangeType). Review documentation for more details regarding the ChangeTypes UpdateInformation, CreateOffer, UpdateTargeting, UpdateLegalTerms, UpdateAvailability, ReleaseOffer).
{
"catalog": "AWSMarketplace",
"changeSet": [
{
"ChangeType": "CreateOffer",
"ChangeName": "CreateOfferChange",
"Entity": {
"Type": "Offer@1.0"
},
"DetailsDocument": {
"ProductId": "prod-1111111111111"
}
},
{
"ChangeType": "UpdateInformation",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"Name": "Test private offer for AmiProduct using AWS Marketplace API Reference Code",
"Description": "Test private offer with hourly annual pricing for AmiProduct using AWS Marketplace API Reference Code"
}
},
{
"ChangeType": "UpdateTargeting",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"PositiveTargeting": {
"BuyerAccounts": [
"111111111111",
"222222222222"
]
}
}
},
{
"ChangeType": "UpdateLegalTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"Terms": [
{
"Type": "LegalTerm",
"Documents": [
{
"Type": "CustomEula",
"Url": "https://s3.amazonaws.com/sample-bucket/custom-eula.pdf"
}
]
}
]
}
},
{
"ChangeType": "UpdateAvailability",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"AvailabilityEndDate": "2023-12-31"
}
},
{
"ChangeType": "UpdatePricingTerms",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {
"PricingModel": "Contract",
"Terms": [
{
"Type": "ConfigurableUpfrontPricingTerm",
"CurrencyCode": "USD",
"RateCards": [
{
"Selector": {
"Type": "Duration",
"Value": "P12M"
},
"RateCard": [
{
"DimensionKey": "t2.micro",
"Price": "220.00"
}
],
"Constraints": {
"MultipleDimensionSelection": "Allowed",
"QuantityConfiguration": "Allowed"
}
}
]
}
]
}
},
{
"ChangeType": "ReleaseOffer",
"Entity": {
"Type": "Offer@1.0",
"Identifier": "$CreateOfferChange.Entity.Identifier"
},
"DetailsDocument": {}
}
]
}Conclusion
In this post, we showed how you can take advantage of AWS Marketplace Catalog API to manage pricing for your s. We also provided decision trees to assist you in selecting the appropriate parameters to invoke the API, based on your business goals as inputs.
Next steps
Streamline your AWS Marketplace operations by integrating the AWS Marketplace Catalog APIs with your existing automation and workflows.
Here are some additional links that to help you learn more about this topic and take advantage of additional AWS Marketplace Features.
- Updating pricing in your AMI products in AWS Marketplace using Catalog APIs
- Automating Private Offers
- Automating Channel Partner Resale Authorization
- Manage Offers with API – Seller Workshop
Feel free to review the GitHub content and suggest changes that are impactful to your business. We welcome your feedback.