Invoicing with the AWS Marketplace

Metronome can automatically bill customers through the AWS Marketplace. This document describes how Metronome works with the AWS Marketplace, some limitations to be aware of when using AWS Marketplace, and the steps required to bill your customers through the Marketplace.

How Metronome works with the AWS Marketplace

Metronome's AWS Marketplace integration is carefully designed to allow billing through AWS without sacrificing the power of Metronome's usage aggregation and pricing. This is achieved by computing pricing on the Metronome side and reporting the total due to AWS Marketplace in the form of a usage-based charge that costs $0.01 per unit. Each hour, Metronome calculates the customer's total bill, subtracts the amount they've already been billed, and sends the difference to AWS. For example, if a customer has a total bill of $100 so far this month, and they've already been billed $75, they'll be billed an additional $25.

Because the AWS Marketplace listing is based just on the total amount due, the full range of pricing options is still available in Metronome. You can still take advantage of tiers, free trials, pricing ramps, prepurchased credits, etc., and customers will see the charges on their regular Amazon Web Services bill.

Limitations of billing through the AWS Marketplace

Billing through the AWS Marketplace has two limitations that are important to be aware of when considering a Marketplace integration:

1. AWS Marketplace only supports positive quantities through their Metering Service, so there's no way to decrease a customer's total bill. For example, consider a customer who was meant to receive $1,000 in credits when they started using your product. Due to a typo, they erroneously received only $100. The mistake is noticed one week into their first billing period, when the customer notices a $500 charge on their AWS bill. In Metronome, this mistake is easily rectified by adding an additional $900 credit, but in AWS, there's no way to reduce that bill.

   If this situation arises, Metronome will stop billing for that customer until their usage catches up to the amount they've already been billed. If this is insufficient to correct the problem, you will need to issue a manual refund through the AWS Marketplace. Please reach out to your Metronome representative if you need to do this so we can help.

2. AWS Marketplace strictly enforces the end of a customer's Marketplace contract. The AWS Marketplace Metering Service only accepts requests for one hour after the customer's contract ends. Metronome typically applies late usage events to an invoice up to 24 hours after the billing period ends, but there is no way to deliver that usage to AWS. Metronome will send one final request to AWS 15 minutes after the scheduled end of a customer's contract. Usage received after that cannot be billed through AWS.

   In the event of an outage, Metronome will catch up when everything comes back online. If Metronome was not able to send usage to AWS for some period of time, the accrued usage will be included in the next request to AWS. However, if the customer's contract has already ended and AWS's one hour grace period has elapsed, Metronome will not be able to bill for the usage accrued during the down time.

Using Tackle

Metronome can bill either directly through the AWS Marketplace or through Tackle. If your company uses Tackle, you can configure Metronome to send billing data through Tackle rather than directly to AWS. The steps in this document still apply, but you'll additionally need to provide Metronome with Tackle API credentials. Work with your Metronome representative to get this set up.

Creating a marketplace listing

Option 1: multiple tiers

1. Create a listing with the "SaaS Contract with Consumption" product type.

2. Set the contract type to "Buyer can choose one tier from the multiple tiers offered."

   

3. Under Set the usage unit category for this product, choose Units.

4. The dimensions you choose should align to the plans you create in Metronome. Most likely this will look like different plan tiers to your customer (e.g. free, basic, pro).

5. The price for these dimensions must be $0. If there are minimums or prepurchased credits associated with a particular plan, this should be handled as in-advance charges in the Metronome plan. These initial fees will be sent in the first hourly update to AWS.

   

6. Under the section Additional usage fee outside of contract, add a single dimension. Make sure the API name is usage_fee and the pricing is $0.01 USD.

   

Option 2: a single tier

Follow the directions from Option 1 except for in Step 4 create a single dimension rather than one for each product tier. All other requirements apply. With this option, instead of having the customer choose their tier/plan via the AWS UI, they will choose their plan when they are redirected to your landing page.

Marketplace listing checklist

If you followed the steps above, you should have an AWS Marketplace listing that will work well with Metronome. The following checklist should help you double check that your listing is correct:

• The type should be SaaS contract with consumption.
• The usage category should be units.
• The buyer should be able to choose just one tier from the tiers offered.
• The price / month for each tier should be $0.
• There should be no additional fees for usage outside this contract for any tier.
• There should be just one additional usage fee outside of contract for the listing. This should not be associated with any of the tiers. The API name should be usage_fee, and the price should be $0.01.

Setting up IAM credentials

In order to make API calls to AWS on behalf of our clients, Metronome needs to be able to assume a role with relevant permissions. The process to create such a role is as follows:

1. Create a policy in your AWS account called something like MetronomeMarketplacePermissions using the policy creator with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "aws-marketplace:BatchMeterUsage",
                "aws-marketplace:GetEntitlements",
                "aws-marketplace:ListEntities",
                "aws-marketplace:DescribeEntity"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

2. Navigate to the role creator. Here you should choose Another AWS account. Enter Metronome's account ID (916227654331) and ask your Metronome representative to generate a unique ID for you to enter in the External ID field. Note that Require MFA should remain unchecked.

   

3. Click Next: Permissions, and under Attach permissions policies, attach the policy you created in step 1.

   

4. Click Next: Tags and add any tags you want. Metronome doesn't require any particular tags.

5. Click Next: Review and name the role metronome-marketplace

   

6. Navigate to the newly created role from the roles page and take note of the role ARN. It should have a format like arn:aws:iam::<AWS_ACCOUNT_ID>:role/metronome-marketplace. Share this ARN with Metronome.

Signing up customers with private offers

When creating a private offer, create a corresponding plan in Metronome. When a customer signs their private offer:

1. Create the customer in Metronome and associate the customer identifier, product ID, and region from AWS. This can be done in one step with the create customer API endpoint. If the customer already exists, you can use the set billing configuration endpoint to add the AWS Marketplace information. Unless you've specifically chosen a different AWS region, you should use us-east-1. If you specify the wrong region, you'll receive an error that the AWS customer cannot be found.
2. Add any credits they should receive. This can be done with the add ledger entry API endpoint or in the customer's Credits tab in the web UI.
3. Assign them the right plan. This can be done with the add plan to customer API endpoint or in the customer's Plans tab in the web UI.

Add credits before assigning the plan

It's important that you add any needed credits before adding the plan to the customer. This is to avoid billing the customer before the credits have been added.

Ending a customer's subscription

AWS will send you a notification when a customer cancels their subscription. When this happens, you can simply end the customer's plan in Metronome. This can be done through the web UI by navigating to the customer, clicking the Plans tab, and choosing End plan from the settings menu. Alternately, this can be done programmatically with the end customer plan API endpoint.