SaaS customer onboarding - AWS Marketplace
Configuring your SaaS product to accept new buyers

SaaS customer onboarding

With software as a service (SaaS) subscriptions and SaaS contracts, your customers subscribe to your products through AWS Marketplace but access the product in your AWS environment. After subscribing to the product, your customer is directed to a website you create and manage as a part of your SaaS product to register their account and configure the product.

When creating your SaaS product listing, you provide a URL to your registration landing page. We use that URL to redirect customers to your registration landing page after they subscribe. On your software's registration landing page, you collect whatever information is required to create an account for the customer. We recommend collecting your customer’s email addresses if you plan to contact them through email for usage notifications.

The registration landing page must be able to identify and accept the x-amzn-marketplace-token token in the form data from AWS Marketplace with the customer’s identifier for billing. It should then pass that token value to the AWS Marketplace Metering Service to resolve for the unique customer identifier, customer AWS account Id, and corresponding product code. For a code example, see ResolveCustomer code example.

Note

The registration token resolves to a specific subscribed customer and each generated token has an expiration window of 4 hours. As long as the caller is calling the API with the same token, it will keep returning the same response values until the token expires.

Configuring your SaaS product to accept new buyers

You're responsible for correctly configuring your SaaS software to accept new customers and meter them appropriately. The following process outlines one recommended way of identifying, implementing, and metering a new customer's access to your software:

  1. When a customer visits your product page on the AWS Marketplace website, they choose to subscribe to your product.

  2. The customer’s AWS account is subscribed to your product. This means subscription and metering records sent from your product become part of the customer’s AWS bill.

  3. A registration token is generated for the customer that contains their customer identifier and your product code.

  4. The customer is redirected to your software's registration landing page. This page must be able to accept the token with the customer’s identifier.

  5. The customer’s browser sends a POST request to your software's registration landing page URL. The request contains one POST parameter, x-amzn-marketplace-token, containing the customer’s registration token. From the perspective of your registration website, the customer has submitted a form with this parameter. The registration token is an opaque string. If the offer type is a free trial, a second parameter, x-amzn-marketplace-offer-type with the value free-trial, will be added to the request.

  6. To redeem this registration token for a customer identifier, customer AWS account Id, and product code, your website must call ResolveCustomer on the AWS Marketplace Metering Service. The customer identifier isn't the customer’s AWS account ID, but it's universal between products and should be saved to an internal source as part of your customer records. The product code is a unique string for your SaaS product that AWS provides to you. Each AWS product has one unique product code, which is assigned to you during registration.

    Note

    To see an example of a ResolveCustomer call, see ResolveCustomer code example.

  7. The customer is instructed to either create an account in your product or sign in to an existing account.

    Note

    If setting up or linking to an existing customer account in your product requires a manual process by your team, you can use a contact-us form to collect the customer's contact information. After collecting their contact information and resolving their AWS Marketplace unique customer identifier (as obtained in step 6), display a notification message for the customer. In the notification, state that their account is being set up and ask that they wait for you to contact them. Provide the customer with the expected turnaround time and your contact information. Also send an email message to the customer with the same details.

  8. The customer is now signed in to your website using credentials specific to that SaaS product. In your accounts database, you can have an entry for each customer. Your accounts database must have a column for the AWS customer identifier, which you populate with the customer identifier that you obtained in step 6. Verify that no other accounts in your system share this customer identifier. For customers who subscribe to multiple products through AWS Marketplace, the customer identifier will remain the same, with each subscription having a unique product code.

  9. During your seller registration process, you subscribe to Amazon SNS topics that notify you when customers subscribe or unsubscribe to your product. These are Amazon SNS notifications in JSON format that inform you of customer actions:

    • Entitlement notification – For products with pricing models that include a contract, you are notified when buyers create a new contract, upgrade it, renew it, or it expires. Your accounts database must have an extra column for the subscription state. For more information, see Amazon SNS topic: aws-mp-entitlement-notification.

    • Subscription notification – For products with any pricing model, including contracts and subscriptions, you are notified when a buyer subscribes or unsubscribes to a product. For more information, see Amazon SNS topic: aws-mp-subscription-notification.

    We recommend that you use Amazon Simple Queue Service (Amazon SQS) to capture these messages. After you receive a subscription notification with subscribe-success, the customer account is ready for metering. Records that you send before this notification aren't metered. For information about how to do this, see Step 2: Give permission to the Amazon SNS topic to send messages to the Amazon SQS queue in the Amazon Simple Notification Service Developer Guide.

    Note

    Do not activate a product subscription unless you receive a subscribe-success notification.

  10. Use the customer identifier stored in your database to meter for usage through the AWS Marketplace Metering Service or check for entitlements through the AWS Marketplace Entitlement Service.

Security and ordering

As a seller, it’s your responsibility to trust only customer identifiers that are immediately returned from AWS or those that your system has signed. We recommend that you resolve the registration token immediately because it may expire after approximately 1 hour. After you resolve the registration token, store the customer identifier as a signed attribute on the customer’s browser session until the registration is complete.