Step-by-Step Guide to SaaS Integration with AWS Marketplace

AWS Marketplace offers third-party Software-as-a-Service (SaaS) products that help organizations reduce operational costs and deployment time. Organizations, from startups to enterprises, can quickly find, evaluate, and subscribe to third-party SaaS solutions through a streamlined procurement process. These solutions eliminate infrastructure management overhead and accelerate time-to-value for business applications.

When listing new products, sellers need to complete the SaaS integration requirements. In this post, we focus on the specific steps needed to integrate SaaS products. This post guides you through the integration requirements for listing your SaaS product in AWS Marketplace. It serves as a complement to our existing resources, including a SaaS quick start, supporting documentation, and labs.

AWS Marketplace SaaS integration consists of several sequential steps. The ResolveCustomer API validates customers by exchanging tokens for customer IDs. The GetEntitlement API verifies contract dimensions, while Amazon Simple Notification Service (Amazon SNS) topics monitor subscription changes. AWS Marketplace offers both standard and consumption-based pricing models, with vendors tracking usage through the BatchMeterUsage operation. This integration delivers secure authentication and access management while streamlining the customer onboarding process.

We will go through the process of completing a SaaS integration and use an example to showcase what is needed for a SaaS contract with consumption product.

Prerequisites

You must have completed the following prerequisites:

• Have AWSMarketplaceSellerFullAccess permission
• Register as a seller on AWS Marketplace
• Create a SaaS product in AWS Marketplace
• Publish your SaaS listing to a limited stage in AWS Marketplace
• Have your SaaS fulfillment URL (landing page) ready

SaaS contract with consumption integration

Figure 1: SaaS integration flow diagram

Step 1: Accepting new customers

Customers subscribe to your SaaS product in AWS Marketplace. AWS Marketplace redirects customers to your registration landing page. You host and manage this landing page within your AWS infrastructure, which initiates the customer onboarding process. On the landing page, customers can create their accounts, begin product configuration, and access your service environment.

Set up a registration landing page within your AWS infrastructure and provide the URL to your SaaS listing. Configure the page to accept and process the x-amzn-marketplace-token.

Step 2: Verifying new customers

After a customer subscribes to your product, they will be redirected to the fulfillment URL (your landing page). The redirect is a POST request and includes a temporary token, valid for 4 hours.

The following diagram shows the workflow to verify new customers in step 2 above.

Figure 2: AWS Marketplace customer verification and entitlement check process flow

Your SaaS integration needs to exchange the token for a customerID by calling the ResolveCustomer API in the AWS Marketplace Metering Service.

The following code example is the request you submit. Add in the regToken value for your use case:

Figure 3: Sample code to exchange token for customer ID

The following is the response from AWS Marketplace:

Figure 4: Response from AWS Marketplace after exchanging token for customer ID

After obtaining a customerID, persist it in your application or database for future calls.

With the customerID, call GetEntitlement in AWS Marketplace Entitlement Service to verify which dimension the customer is subscribed to and the quantity, if applicable. This is shown in the next step.

Step 3: Subscribe to the SNS topics

Set up the Amazon Simple Queue Service (SQS) queue and subscribe to the SNS topics. This provides notifications about changes to customer’s subscription and entitlement statuses. This indicates when to provide and revoke access for specific customers. Possible scenarios include unsubscribes, upgrades, renewals, and failed subscription.

• To create an SQS entitlement, enter the following configurations:
  • Name: Give the name of your choice
  • Configuration: Leave them as default
  • Encryption: Leave them as default
  • Access policy: Advanced
    • Resource: arn:aws:sqs:region:awsaccountid:name_of_your_sqs
    • ArnEquals: Copy this from your AWS Marketplace account under Entitlement Service SNS topic ARN

This SQS queue policy allows AWS Marketplace to send entitlement notifications to your queue. To send the sqs message, enter the following command.

• To create the SQS subscription, enter the following configurations:
  • Name: Give the name of your choice, for example, SaaS_Contract_with_Consumption_Subscription_SQS
  • Configuration: Leave them as default
  • Encryption: Leave them as default
  • Access policy: Advanced
    • Resource: arn:aws:sqs:region:awsaccountid:<name of queue>r_
    • ArnEquals: Copy this from your AWS Marketplace account under Metering Service SNS topic ARN
    • This SQS queue policy allows AWS Marketplace to send subscription notifications to your queue when customers subscribe to or unsubscribe from your SaaS product or otherwise modify their subscription.

Step 4: Verifying entitlements

The following code example is the request from your SaaS integration:

Figure 5: Request from SaaS integration

The following code is the response from AWS Marketplace:

Figure 6: Response from AWS Marketplace

If the entitlement is active, grant access to the buyer based on dimensions and contract duration returned in entitlement. If no entitlement is returned from GetEntitlement, either during onboarding or ongoing verification, determine how to manage access.

Each time the entitlement is updated, you will receive the message on the SNS topic. The Lambda function entitlement-sqs.js on each message is calling the marketplaceEntitlementService and storing the response (CustomerIdentifier and the ProductCode) in DynamoDB. We’re using the same DynamoDB stream to detect changes in the entitlement for SaaS contracts.

• To trigger the Lambda entitlement with the SQS entitlement, follow these steps:
  • In your register-new-subcriber.js Lambda function will check if entitlement queue exists and sends SQS message with entitlement update notification containing:
    • Action type: “entitlement-updated”
    • Customer identifier
    • Product code

Figure 7: Checking entitlements

• Create the SQS Lambda entitlement-sqs.js. For more information, refer to the sample code in aws-marketplace-serverless-saas-integration
• In the SQS Lambda entitlement, add the SQS entitlement created in step 3 as a trigger:
  • In the Lambda function, choose Configuration then Triggers.
  • Choose Add trigger then choose SQS.
  • Select your SQS queue
  • Under Batch size, select 1–10 messages per invocation.
  • Attach an AWS Identity and Access Management (IAM) policy to the SQS Lambda entitlement to allow it to receive messages from the SQS entitlement.
  • You will need to attach an IAM policy to the SQS lambda entitlement to allow it to receive message from the SQS Entitlement.

Step 5: Account creation and product configuration workflows

Implement partition creation and product configuration workflows after verifying the new customer if your workflow handles automation. If your SaaS platform doesn’t offer automatic onboarding, include a message on your landing page to inform the buyer that a representative will contact them in a set period to start the platform onboarding process.

Step 6: For SaaS metered usage

For AWS Marketplace SaaS subscriptions, sellers must meter customer usage for AWS billing purposes. With standard subscriptions, all usage is metered. For SaaS contracts with consumption, metering only applies to usage exceeding contract entitlements. When metering, your application reports usage quantities to AWS based on your predefined pricing dimensions, such as data transferred or scanning activity.

Create an Amazon CloudWatch Events rule called MeteringSchedule that triggers hourly. This rule executes the metering-hourly-job.js script, which performs two main functions:

1. Queries the AWSMarketplaceMeteringRecords table for pending or unreported metering records using PendingMeteringRecordsIndex

2. Aggregates these records by customerIdentifier and dimension name before sending them to the SQSMetering queue

The AWSMarketplaceMeteringRecords table requires programmatic updates from your SaaS application. To enable this, grant appropriate write permissions to your usage data collection service for the AWSMarketplaceMeteringRecords table.

The AWS Lambda function metering-sqs.js sends queued metering records to the AWS Marketplace Metering service. After every call to the batchMeterUsage endpoint, the rows are updated in the AWSMarketplaceMeteringRecords table, with the response returned from the Metering Service, which can be found in the metering_response field. If the request was unsuccessful the meteringfailed value with be set to true and you will have to investigate the issue the error will be also stored in the metering_response field.

• Code example to report customer consumption using AWS Marketplace Metering Service batch API

Figure 8: Code sample for batch metered usage

• Store new records in the AWS Marketplace Metering Records table using this format:

Figure 9: Record stored table format

The table uses two key components for its primary key: customerIdentifier serves as the partition key, while create_timestamp functions as the sort key. Together, these form the complete primary key. The new records format is in DynamoDB JSON format, which is different than JSON. The accepted time stamp is UNIX timestamp in UTC time.

• After the record is submitted to the AWS Marketplace BatchMeterUsage API, it will be updated to look like this:

Figure 10: Record submitted to AWS Marketplace

End-to-end testing in AWS Marketplace

Testing the AWS Marketplace buyer journey after integration ensures smooth customer experience and proper AWS service connections by simulating the complete customer lifecycle and verifying key API functionality.

Clean up

1. Delete all IAM roles created from the blog
2. Delete SNS subscription(s) that notify your email
3. Delete lambda
4. Delete DynamoDB table

Conclusion

This guide explains the Software-as-a-Service (SaaS) integration process with AWS Marketplace. To begin selling your SaaS products, list them in AWS Marketplace and complete the integration requirements. AWS Marketplace connects you directly with AWS customers, provides automated billing, and simplifies procurement processes. For more resources on listing SaaS products in AWS Marketplace review our labs and official documentation. If you have questions about your listings, you can use the contact us webform in your AWS Marketplace seller account to submit a ticket.

About Authors