AWS Marketplace

SaaS Listing Process &

Integration Guide

1 © 2019, Am azon Web Ser vices, Inc. or its affiliates. All ri ghts reserved.
AWS Marketplace SaaS Guide / About this guide

About this guide

Audience
This guide is for independent software vendors (ISVs), selling SaaS products in AWS Marketplace. We have included
essential information to help you navigate each step of the listing process and understand what s required to
integrate with AWS Marketplace. In this guide, you will find integration diagrams for each pricing model, code
examples for interacting with our APIs, a list of frequently asked seller questions, and links to external resources that
help you deep dive into the concepts presented throughout. Thank you for choosing to list with us and we look
forward to welcoming you to AWS Marketplace!

Before Getting Started

There are some prerequisites you ll need to complete before submitting your SaaS product and reviewing this guide :

1. Register as a seller and submit tax & banking information. This step is required before you can request to list a
paid product. Click here to learn how to register & submit tax and banking information.
2. Become familiar with the AWS Marketplace Management Portal (AMMP). This is the tool that you use to
register as a seller and manage the products that you sell on AWS Marketplace. Click here to learn about AMMP.
3. Learn about tools available to you as an AWS Marketplace seller. Click here for your seller toolkit.
4. Determine your product s pricing model. SaaS products can be created with one of three pricing options:
Contract, Contract with Consumption, or Subscription.
Click here to learn more about Contract pricing (or) Click here to learn more about Subscription pricing

Contents
SaaS Contract (upfront billing) Code examples
Listing process & integration requirements ResolveCustomer

Integration diagram GetEntitlement

BatchMeterUsage
SaaS Contract with Consumption
Listing process & integration requirements Frequently Asked Questions (FAQs)
Integration diagram
External resources
SaaS Subscription (pay-as-you-go)
Listing process & integration requirements

Integration diagram

2 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / SaaS Contract

SaaS Contract
Listing process &
integration requirements

Integration diagram

3 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
 AWS Marketplace SaaS Guide / SaaS Contract / Listing Process & Integration Requirements

SaaS Contract
Note: Each item refers to a step in the diagram (see next page)

Listing Process
1 Collect Assets 5 Onboard New Customers
Before submitting a product, you will need to provide: After successfully verifying a customer s subscription, onboard them onto your
application. For example, have them fill out a form to create a new user account. Or,
 Product logo URL provide them with next steps to get access to the application.
 End User License Agreement (EULA) URL
 SaaS fulfillment URL (redirect page customers will be sent to after subscribing) 6 Handle No Entitlement Scenarios
If no entitlement is returned from GetEntitlement, either during onboarding or
 Metadata
ongoing verification, determine how to manage access & their experience.
 Support information

2 Submit via Management Portal 7 Monitor for Changes

Create a product page using a seller account that has access to the AWS Marketplace Setup an SQS queue and subscribe to your product s SNS topic. This topic provides
Management Portal (AMMP). notifications about changes to customers subscription and entitlement statuses. This
enables you to know when to provide and revoke access for specific customers. Possible
3 Product Page Published to Limited scenarios include: unsubscribes, upgrades, renewals, & failed subscription.
The AWS MP Ops team will publish your submission as a limited product page visible to
you and any AWS accounts you have requested to be whitelisted. Prices will be
temporarily reduced to enable you to test the purchase flow without incurring high Listing Process (continued after completion of integration)
charges. The Ops team will send you the following via email to enable this testing:
8 End-to-end testing with AWS Marketplace
 Product code After you have completed all the integration requirements and tested the solution,
 SNS topic(s) notify the AWS Marketplace Ops team. They will then test the solution by verifying you
 Product page URL have successfully called GetEntitlement and sufficiently onboard new customers.

After end-to-end testing is complete, you will have the chance to review the product
Integration Requirements page with the original prices. After giving approval, the AWS Marketplace Ops team will
4 Validate New Customers make the product page live in the public catalog.
After a customer subscribes to your product, they will be redirected to the fulfillment URL.
The redirect is a POST request & includes a temporary token. Your app then needs to:
 Exchange the token for a customerID by calling ResolveCustomer in the AWS
Marketplace Metering Service.
 After obtaining a customerID, persist it in your application for future calls.
 With the customerID, call GetEntitlement in the AWS Marketplace Entitlement Service
to verify which dimension the customer is subscribed to and the quantity, if applicable.

4 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / SaaS Contract / Integration Diagram

SaaS Contract (cont.) Key:

1 2 3 8 ES = AWS Marketplace Entitlement Service API

Submit AWS MP
Determine AWS MP End-
Decide to List Product Publishes SaaS
pricing & offer to-End Product Live
SaaS Product via Product to Integration
type Testing
AMMP Limited MS = AWS Marketplace Metering Service API
Review SaaS
Collect Assets
Seller Guide
X = Steps (see previous page)

Accepting New X = Code example (see code example pages)

Monitoring for
4 Customers
Subscription Changes

Accept HTTP POST = AWS Service

request
x-amzn-marketplace-
Verifying
token
Customers
= Seller (ISV) Action

A
MS
= AWS Marketplace Ops Team Action
Subscribe Setup new
Call
Store CustomerID With CustomerID to: queue in SQS
ResolveCustomer

B
7
Call GetEntitlement Example SNS Topic
Check customer s arn:aws:sns:us-east-1:287250355862:aws-mp-
If no entitlement returned to verify active Listen for:
entitlement entitlement-notification-PRODUCTCODE
subscription
ES
entitlement-updated
Entitlement
DB message
SNS topic
6
If active entitlement

Handle each scenario

5
Grant access to
New customers in Existing customers product based on
onboarding workflow already using product dimensions returned
in entitlement

5 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / SaaS Contract with Consumption

SaaS Contract
with Consumption
Listing process &
Integration requirements

Integration diagram

6 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
 AWS Marketplace SaaS Guide / SaaS Contract with Consumption / Listing Process & Integration Requirements

SaaS Contract with Consumption

Note: Each item refers to a step in the diagram (see next page)

Listing Process 5 Onboard New Customers

After successfully verifying a customer s subscription, onboard them onto your
1 Collect Assets application. For example, have them fill out a form to create a new user account. Or,
Before submitting a product, you will need to provide: provide them with next steps to get access to the application.
 Product logo URL
 End User License Agreement (EULA) URL
6 Handle No Entitlement Scenarios
If no entitlement is returned from GetEntitlement, either during onboarding or
 SaaS fulfillment URL (redirect page customers will be sent to after subscribing) ongoing verification, determine how to manage access & their experience.
 Metadata
 Support information 7 Sending Metering Records
You use the BatchMeterUsage operation in the AWS Marketplace Metering Service to
2 Submit via Management Portal deliver metering records to AWS on behalf of your customers. We recommend using
Create a product page using a seller account that has access to the AWS Marketplace CloudTrail to monitor activity to ensure that billing information is being sent to AWS
Management Portal (AMMP). Marketplace. Keep in mind when sending metering records:
 Marketplace de-duplicates metering requests on the hour
3 Product Page Published to Limited
 Records sent every hour are cumulative
The AWS MP Ops team will publish your submission as a limited product page visible to
you and any AWS accounts you have requested to be whitelisted. Prices will be  Best practice is to send records every hour, even if quantity is 0
temporarily reduced to enable you to test the purchase flow without incurring high
charges. The Ops team will send you the following via email to enable this testing: 8 Monitor for Changes
 Product code Setup an SQS queue and subscribe to your product s SNS topics. These topics provide
 SNS topic(s) notifications about changes to customers subscription and entitlement statuses. This
enables you to know when to provide and revoke access for specific customers. Possible
 Product page URL scenarios include: unsubscribes, upgrades, renewals, & failed subscription.

Integration Requirements Listing Process (continued after completion of integration)

4 Validate New Customers 9 End-to-end testing with AWS Marketplace
After a customer subscribes to your product, they will be redirected to the fulfillment URL.
After you have completed all the integration requirements and tested the solution,
The redirect is a POST request & includes a temporary token. Your app then needs to:
notify the AWS Marketplace Ops team. They will then test the solution by verifying you
 Exchange the token for a customerID by calling ResolveCustomer in the AWS have successfully called GetEntitlement and sufficiently onboard new customers.
Marketplace Metering Service. They will also verify you have successfully sent metered records via BatchMeterUsage.
 After obtaining a customerID, persist it in your application for future calls.
After end-to-end testing is complete, you will have the chance to review the product
 With the customerID, call GetEntitlement in the AWS Marketplace Entitlement Service
page with the original prices. After giving approval, the AWS Marketplace Ops team will
to verify which dimension the customer is subscribed to and the quantity, if applicable. make the product page live in the public catalog.

7 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / SaaS Contract with Consumption / Integration Diagram

SaaS Contract with Consumption (cont.) Key:

1 2 3 9 ES = AWS Marketplace Entitlement Service API

Submit AWS MP
Determine AWS MP End-
Decide to List Product Publishes SaaS
pricing & offer to-End Product Live
SaaS Product via Product to Integration
type Testing
AMMP Limited MS = AWS Marketplace Metering Service API
Review SaaS
Collect Assets
Seller Guide
X = Steps (see previous page)
7
Accepting New Reporting X = Code example (see code example pages)
4 Monitoring for
Customers Metered Records Subscription Changes

Accept HTTP POST = AWS Service

request
x-amzn-marketplace-
Verifying Metering Send
token
Customers
C = Seller (ISV) Action

Send record to Log API calls to

A BatchMeterUsage CloudWatch
MS
= AWS Marketplace Ops Team Action
Subscribe Setup new Subscribe
Call
Store CustomerID With CustomerID to: queue in SQS to:
ResolveCustomer

Call GetEntitlement 8
Check customer s
If no entitlement returned to verify active Listen for: Example Entitlement SNS Topic
entitlement
subscription arn:aws:sns:us-east-1:287250355862:aws-mp-
ES
entitlement-updated entitlement-notification-PRODUCTCODE
Entitlement Subscription
DB message
SNS topic SNS topic
6 Example Subscription SNS Topic
8 arn:aws:sns:us-east-1:287250355862:aws-mp-
If active entitlement Listen for and handle each scenario: subscription-notification-PRODUCTCODE

Handle each scenario

5
Grant access to
New customers in Existing customers product based on
onboarding workflow already using product dimensions returned
in entitlement unsubscribe-success subscribe-fail unsubscribe-pending subscribe-success
message message message message

8 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / SaaS Subscription

SaaS Subscription
Listing process &
Integration requirements

Integration diagram

9 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
 AWS Marketplace SaaS Guide / SaaS Subscription / Listing Process & Integration Requirements

SaaS Subscription
Note: Each item refers to a step in the diagram (see next page) 5 Onboard New Customers
After successfully verifying a customer, onboard them onto your application. For
Listing Process example, have them fill out a form to create a new user account. Or, provide them with
next steps to get access to the application.
1 Collect Assets
Before submitting a product, you will need to provide: 6 Sending Metering Records
 Product logo URL You use the BatchMeterUsage operation in the AWS Marketplace Metering Service to
 End User License Agreement (EULA) URL deliver metering records to AWS on behalf of your customers. We recommend using
CloudTrail to monitor activity to ensure that billing information is being sent to AWS
 SaaS fulfillment URL (redirect page customers will be sent to after subscribing) Marketplace. Keep in mind when sending metering records:
 Metadata  Marketplace de-duplicates metering requests on the hour
 Support information  Records sent every hour are cumulative
 Best practice is to send records every hour, even if quantity is 0
2 Submit via Management Portal
Create a product page using a seller account that has access to the AWS Marketplace
7 Monitor for Changes
Management Portal (AMMP).
Setup an SQS queue and subscribe to your product s SNS topic. This topic provides
notifications about changes to customers subscription. This enables you to know when
3 Product Page Published to Limited to provide and revoke access for specific customers. Possible scenarios include:
The AWS MP Ops team will publish your submission as a limited product page visible to unsubscribes, successful subscription, & failed subscription.
you and any AWS accounts you have requested to be whitelisted. Prices will be
temporarily reduced to enable you to test the purchase flow without incurring high 8 Verify Successful Subscription
charges. The Ops team will send you the following via email to enable this testing: After you receive a subscription notification with subscribe-success, the customer
 Product code account is ready for metering. Records that you send before this notification aren't
 SNS topic(s) metered. Additionally, we recommend waiting for this message before launching
resources on behalf of a customer.
 Product page URL
Listing Process (continued after completion of integration)
Integration Requirements
9 End-to-end testing with AWS Marketplace
4 Validate New Customers After you have completed all the integration requirements and tested the solution,
After a customer subscribes to your product, they will be redirected to the fulfillment URL. notify the AWS Marketplace Ops team. They will then test the solution by verifying you
The redirect is a POST request & includes a temporary token. Your app then needs to: have successfully sent metered records via BatchMeterUsage and sufficiently onboard
 Exchange the token for a customerID by calling ResolveCustomer in the AWS new customers.
Marketplace Metering Service.
 After obtaining a customerID, persist it in your application for future calls. After end-to-end testing is complete, you will have the chance to review the product
page with the original prices. After giving approval, the AWS Marketplace Ops team will
make the product page live in the public catalog.

10 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / SaaS Subscription / Integration Diagram

SaaS Subscription (cont.) Key:

1 2 3 9 MS = AWS Marketplace Metering Service API

Submit AWS MP
Determine AWS MP End-
Decide to List Product Publishes SaaS
pricing & offer to-End Product Live
SaaS Product via Product to Integration
type Testing
AMMP Limited
X = Steps (see previous page)
Review SaaS
Collect Assets
Seller Guide
X = Code example (see code example pages)
6
Accepting New Reporting
4 Monitoring for = AWS Service
Customers Metered Records Subscription Changes

Accept HTTP POST

request = Seller (ISV) Action
x-amzn-marketplace-
Verifying Metering Send
token
Customers
C
= AWS Marketplace Ops Team Action
Send record to Log API calls to
A BatchMeterUsage CloudWatch
MS
Setup new Subscribe
Call
Store CustomerID queue in SQS to:
ResolveCustomer

Example Subscription SNS Topic

arn:aws:sns:us-east-1:287250355862:aws-mp-
subscription-notification-PRODUCTCODE

Subscription
DB SNS topic
7
Listen for and handle each scenario:

Grant access to
product
unsubscribe-success subscribe-fail unsubscribe-pending subscribe-success
message message message message

8
Verify you receive subscribe-success
before spinning up resources on behalf of customers

11 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / Code Examples

Code Examples
ResolveCustomer

GetEntitlement

BatchMeterUsage

12 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
 AWS Marketplace SaaS Guide / Code Examples / A - ResolveCustomer

A ResolveCustomer
Pricing Models
This code example is relevant for all pricing models (i.e. Contract, Contract with Consumption, & Subscription).

Purpose
Exchanging x-amzn-marketplace-token for customerID.

Example (Python) Response from ResolveCustomer

Reference
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/meteringmarketplace.html#MarketplaceMetering.Client.resolve_customer

13 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
 AWS Marketplace SaaS Guide / Code Examples / B - GetEntitlement

B GetEntitlement
Pricing Models
This code example is relevant for SaaS Contract & Contract with Consumption.

Purpose
Verify that a customer has an active entitlement. Identify which dimension(s) that customer is subscribed to.

Example (Python) Response from GetEntitlement

Note: the Value returned will correspond to the API dimensions created when
setting up the product in the AWS Marketplace Management Portal (AMMP)

Reference
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/marketplace-entitlement.html#MarketplaceEntitlementService.Client.get_entitlements

14 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
 AWS Marketplace SaaS Guide / Code Examples / C - BatchMeterUsage

C BatchMeterUsage
Pricing Models
This code example is relevant for SaaS Subscription & Contract with Consumption.

Purpose
Send a metering record to AWS Marketplace.

Example (Python) Response from BatchMeterUsage

Reference
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/meteringmarketplace.html#MarketplaceMetering.Client.batch_meter_usage

15 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / Frequently Asked Questions (FAQs)

Frequently Asked Questions (FAQs)

Entitlements
How can I audit my existing entitlements?
You can create a job to periodically call GetEntitlements for all customer identifiers in your database. AWS
throttles your call volume to 10 TPS.

Should I revoke access on the expiration date indicated in the entitlement document if I don t
receive a notification that the entitlement document has been updated?
No. Your product should wait for an entitlement update or periodically check GetEntitlements to verify that the
allocation should be revoked. Use the expiration field only to notify customers of a possible loss in allocated
resources. Don't use the information in this field to limit functionality. Amazon SNS notifications are delivered with
best effort, so your product should check GetEntitlements before revoking access.

Private Offers
How do I transact with private offers for SaaS-based products?
Before transacting with a private offer, your SaaS product must have a publicly available dimension similar to the
service you intend to include in the private offer. Additionally, the offer must match durations already enabled in
your product. Private offers augment the public offering (pricing, dimension and EULA) but do not change the
technical integration. Click here to read more about getting started with private offers.

Customer Experience
Can a customer downgrade their contract?
No. Customers can only upgrade to one of a higher value except for longer durations. For example, they can upgrade
to higher quantities or higher-value entitlements. Customers are given a prorated credit for their existing contract.
Customers can't decrease the size of their existing contract. They can only decrease the size at renewal, or cancel
their renewal.

Testing Your Integration

What should I test when integrating my product with AWS Marketplace?
We recommend you test: new customer registration, existing customer registration, duplicate accounts,
unsubscriptions, metering records successfully sent (SaaS subscription only), and metering records captured by AWS
CloudTrail (SaaS subscription only). Click here for more details about testing.

How do I subscribe to my product while testing?

During the onboarding process, we recommend you create a second AWS account ID for testing. During the listing
process, you can whitelist this additional account. Only accounts that are whitelisted can view and subscribe to the
product. You sign in to the test account to view your SaaS product on AWS Marketplace and use it to verify the
metering and billing process on an ongoing basis.

Cancellations
How do I handle cancellations?
Customers cancel SaaS subscription products through their AWS account. When a customer cancels a subscription,
you receive a notification, and you have 1 hour to send a final metering record for the customer. You notify the
customer from your product that the cancellation is in progress. If a customer indicates that they want to cancel
through your product, direct the customer to AWS Marketplace.

For SaaS contract products, customers can request a cancellation and refund within 48 hours through AWS Support.
When a customer cancels a contract, you receive a notification, and have 1 hour to send a final metering record for
the customer for any additional usage charges.

16 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Marketplace SaaS Guide / External resources

External Resources
Below are resources to help get you started as a SaaS seller. Click each link to open the resource in your browser.

AWS Marketplace Seller Guide

Software-as-a-Service Overview

SaaS Purchase Flow

Testing Your SaaS Product

Reporting

Private Offers
Seller Private Offers Overview

AWS Marketplace Enhanced Data Sharing Program

Developers
AWS Marketplace Metering Service API Reference

AWS Marketplace Entitlement Service API Reference

IAM Policy for SaaS Products

AWS SDKs

Blog Articles
How to Best Architect Your AWS Marketplace SaaS Subscription Across Multiple AWS Accounts

7 Tips to Successfully Submit Your Product Listing in AWS Marketplace

Going to Market with SaaS Subscriptions and Contracts in AWS Marketplace

Tutorials
Creating an Amazon SQS Queue

Subscribing an Amazon SQS Queue to an Amazon SNS Topic

Delegate Access Across AWS Accounts Using IAM Roles

Sending Amazon SNS Messages to an Amazon SQS Queue in a Different Account

17 © 2019, Amazon Web Services, Inc. or its affiliates. All rights reserved.