Invoicing with AWS Marketplace

Metronome's AWS Marketplace integration combines AWS billing with Metronome's usage aggregation and pricing capabilities. Learn how to set up and configure an integration to automatically bill customers through the AWS Marketplace.

Prerequisites

To invoice through the AWS Marketplace, you need:

• An AWS account
• A unique ID for the External ID field during the AWS role creator phase; ask your Metronome representative to generate this for you
• Your Tackle credentials, if you choose to bill through Tackle
• To review and accept the known limitations

Bill through Tackle

Metronome can send billing data through Tackle rather than directly to AWS. The set up steps are the same, except you need to first provide your Tackle API credentials to your Metronome representative.

How Metronome works with the AWS Marketplace

Pricing is computed on the Metronome side and the total due is reported to AWS Marketplace in the form of a usage-based charge at a cost of $0.01 per unit. Every 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.

Since the AWS Marketplace listing is based on the total amount due, the full range of pricing options is still available in Metronome, such as tiers, free trials, and pre-purchased credits. Customers see the Metronome charges on their regular AWS bill.

Create a marketplace listing

Begin by creating an AWS Marketplace listing. The listing must have certain properties:

• 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.

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

2. Set the contract type to support multiple tiers or a single tier.

   

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

4. Select the dimensions based upon the number of tiers.

   For multiple tiers, the dimensions you choose should align to the plans you create in Metronome. Most likely this looks like different plan tiers to your customer (for example, free, basic, pro).

   For a single tier, 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 through the AWS UI, they choose their plan when they are redirected to your landing page.

5. Set the dimension prices.

   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 are 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.

   

Set up IAM credentials

To make API calls to AWS on your behalf, Metronome needs a role with the right permissions:

1. Go to the AWS policy creator.
2. Create a policy and give it a meaningful name, like MetronomeMarketplacePermissions.
3. Specify the following permissions:

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

5. Configure the new AWS role.

   Navigate to the role creator. Choose Another AWS account. Enter Metronome's account ID (916227654331) and enter the unique ID (generated for you by your Metronome representative) in the External ID field. Keep Require MFA unchecked.

   

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

   

7. Click Next: Tags and add any desired tags.

   Tags are optional; your AWS Marketplace integration works with Metronome without them.

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

   

9. Share the role's ARN value with your Metronome representative.

   To find the value, navigate to the newly created role from the roles page. The ARN is in the format arn:aws:iam::<AWS_ACCOUNT_ID>:role/metronome-marketplace.

Sign up customers with private offers

When creating a private offer, make 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.

   Do this in one step with the /customers endpoint. If the customer already exists, you can use the /customers/{customer_id}/billing-config/{billing_provider_type} endpoint to add the AWS Marketplace information. Unless you've specifically chosen a different AWS region, 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.

   Do this with the /credits/createGrant endpoint or in the customer's Credits tab in the Metronome app.

3. Assign them the right plan.

   Do this with the /customers/{customer_id}/plans/add endpoint or in the customer's Plans tab in the Metronome app.

Add credits before assigning the plan

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

End a customer's subscription

AWS sends you a notification when a customer cancels their subscription. When this happens, you can just end the customer's plan in Metronome. Do this through the Metronome app by navigating to the customer, clicking the Plans tab, and choosing End plan from the settings menu. Do this programmatically with the /customers/{customer_id}/plans/{customer_plan_id}/end endpoint.

Limitations of AWS Marketplace

Billing through the AWS Marketplace has two limitations:

• AWS Marketplace only supports positive quantities through their Metering Service.

  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 stops 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 must issue a manual refund through the AWS Marketplace. You can reach out to your Metronome representative for help.

• 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 sends 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 catches up when everything comes back online. If Metronome was unable to send usage to AWS for some period of time, the accrued usage is 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 is unable to bill for the usage accrued during the down time.