How to Integrate Your SaaS Service with SaaS Subscriptions for AWS Marketplace

The following is a guest post from David Aiken, Partner Solutions Architect (SA) for AWS Marketplace

The AWS Marketplace SaaS Subscription feature allows customers to find, subscribe and pay for the usage of your SaaS solution through AWS. In this post I’ll give you a quick overview describing the concepts, integration points and how to get started. You can find out more information by registering as a seller with AWS Marketplace and accessing the Seller Portal here.

The metering for the AWS Marketplace SaaS Subscription service is consumption based, meaning you would charge users for things they had done or used at an hourly rate. For example, if your SaaS service managed websites, you would set a price per website. Each hour you would report how many websites were being managed by your service. AWS would do the math and add the total to the customer’s bill for that hour.

When using the AWS Marketplace SaaS Subscription service, you need to determine the type of usage you are going to charge for. The top-level usage type is known as a “category” and can be either Hosts, Users, Data, Bandwidth, Requests or Tiers. You may select only 1 category. Within a category, you can define between 1 and 8 dimensions. Dimensions allow you to distinguish between different usage within a category, for example if the category is users, you could have a dimension for Admin users and charge $0.87/user/hour and another for Standard users charged at $0.22/user/hour.

Integrating with the SaaS Subscription Service

Once you have your category, dimensions and costs figured out, you need to integrate SaaS Subscriptions into your SaaS service. There are three integration tasks to complete:

Customer registration – When a customer subscribes to your service from AWS Marketplace, they will be redirected via an HTTP POST to your registration page. In the POST request will be a form field named x-amzn-marketplace-token. This token can be redeemed via an AWS API call to ResolveCustomer to determine the customer ID of the subscriber and the product code of the service they subscribed too. You should save this alongside any registration information as you will need it when reporting metering usage.

Report usage information – Each hour, you need to report usage information for each customer. You do this via an API call to BatchMeterUsage, sending up to 25 metering records at a time. You would send 1 record per customer per dimension. Each call would include the Customer ID, Dimension Name, Usage Quantity and UTC timestamp.

Handle Subscription events – When a customer subscribes or unsubscribes from your service, messages are sent to an SNS topic created by AWS for your service. It’s a good practice to subscribe an SQS queue to the topic, then read the messages from the queue. This way you won’t lose messages if your service is unavailable. The most important event to handle is the unsubscribe-pending. If you receive this for a customer, you will have 1 hour to report any final usage. After an hour you will receive an unsubscribe-success message, at which time no more metering records can be sent for that customer.

Figure 1: SaaS Subscriptions Integration Points

Getting Started

Before you can start development work, you will need a product to be created in AWS Marketplace. To do this, you will need to use Self-Service Listings, located within the “Listings” tab of the AWS Marketplace Management Portal (AMMP). If you are not already registered for access to AMMP, you must first sign up to access the portal.  To create a new SaaS Subscriptions product, log in to AMMP, navigate to the “Listings” tab, look for the “Create a New Product” box, and choose “SaaS Subscriptions” from the dropdown. You will then be guided through a set of web forms that will help you create your listing.

Once you have completed, reviewed, and submitted the form, the AWS Marketplace operations team will create a product listing for your service and send you the product code, along with the SNS topic. When your product is ready to review, your listing will show up with a status of “Approval Required” under the “Requests” area of Self-Service Listings. You can then click on your request to view your product code, pricing information, limited preview listing, and more. This product will remain hidden in limited preview until you have completed your development work and are ready to go public.

Seller vs Production Accounts

To list a product or SaaS service in AWS Marketplace, you need to register an AWS account to be your seller account. You can only have a single seller account, so you should consider creating a new account just for this purpose.

Calls to the AWS APIs need to be authenticated from the seller account. Rather than hosting your production code in the seller account, or embedding secret/access keys in your production code, you should consider using cross-account AWS Identity and Access Management (IAM) roles. Cross-account IAM roles will allow you to have production code in different accounts than your seller account. This is very useful when you want to maintain a security boundary, or have multiple products to list.

Testing

When building out your integration, you will need to have several AWS accounts available that you can use as test customers. Since the product listing page is hidden during your development, you will need to instruct the AWS Marketplace operations team to authorize specific AWS accounts to view your product. When you create your product in Self-Service Listings, you can identify any additional AWS accounts to authorize by entering them in the “Accounts to Whitelist” field located on the “Pricing” tab. Once an AWS account is authorized, you can use that account to subscribe to your product and perform any testing.

You may also wish to have a test product set up so you can test the subscription workflow, metering and event handling in a different environment than your production code. To create a test product, simply create and submit another SaaS product using Self-Service Listings, making sure to indicate in the title of your product that it is the test version.

Summary

Integrating with SaaS Subscriptions requires you to be registered as a seller in AWS Marketplace and have a SaaS product created. There are three integrations to complete: customer registration, reporting customer usage, and handling subscription events. For more information, please visit the AWS Marketplace SaaS Subscriptions page.