This guide describes how to enable Metronome to invoice on your behalf through AWS Marketplace.

​
Create an AWS Marketplace listing​

  1. To gain access to the AWS marketplace management portal, you must be an approved seller by AWS.
  2. Complete Step 1: Provide product information and Step 2: Configure fulfillment options in the Product Creation Wizard. Metronome does not require specific inputs for these steps, however, you should be aware of the marketplace requirements to post and fulfill your offering.
  3. Choose the Pricing model for your offering and select Units as the Dimension unit type. Metronome supports Contract with Consumption or Usage-based pricing options. This choice will be tied to the sales motion of your product: Contract with Consumption will have fixed-term lengths while Usage-based pricing products can be started or stopped at any time by your customer. You will need to know the product type when configuring the customer in Metronome.
AWS product pricing options
  1. For products that use the Contract with Consumption model create one or more Contract dimensions tied to the sales motions of your product. These dimensions should correspond to the the different pricing models you have set up in Metronome. They will also be used to manage customer lifecycle events such as subscription end and renewal. This step is not required for Usage-based pricing products.
    • Activate pay-as-you-go pricing for additional usage should be unchecked for all dimensions.
    • You can select any values you prefer for the API identifier and Display name.
AWS contract dimensions
  1. Create a single Usage dimension.
CAUTIONThe API identifier must be called usage_fee for the integration to work correctly.
AWS usage dimension
  1. For products that use the Contract with Consumption model, select Single dimension per contract. This step is not required for Usage-based pricing products.
    • For Contract duration options , select the duration that best applies to your product.
AWS purchasing options
  1. When setting up pricing for your listing, set the price for all contract dimensions to $0.
    • For the single usage_fee dimension, set the price to $0.01 per unit.
CAUTIONDeviating from these values will cause the integration to fail.

​
Set up IAM credentials for Metronome to meter on your behalf​

To make API calls to AWS on your behalf, Metronome needs a role with the right permissions. To set up IAM credentials for Metronome:
  1. In AWS, go to the AWS policy creator.
  2. Create a policy and give it a meaningful name, like MetronomeMarketplacePermissions.
  3. Specify these permissions: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "aws-marketplace:BatchMeterUsage",
        "aws-marketplace:GetEntitlements",
        "aws-marketplace:ListEntities",
        "aws-marketplace:DescribeEntity"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
AWS policy
  1. In Metronome, go to Connections > Integrations > Available Integrations > AWS Marketplace > click Get started.
  2. Copy Metronome’s AWS account ID and the unique external ID generated on step 1 of the menu.
AWS external ID
  1. Back in AWS, configure the new AWS role.
      • Go to the role creator > Another AWS account.
      • Enter Metronome’s AWS account ID and the unique external ID copied from the above step in the External ID field.
      • Leave Require MFA unchecked.
AWS role
  1. Click Next: Permissions , and under Attach permissions policies , attach the policy you created in step 2.
AWS permissions
  1. Click Next: Tags and add any desired tags. Tags are optional; your AWS Marketplace integration with Metronome works without them.
  2. Click Next: Review and name the role metronome-marketplace.
CAUTIONThe role name must begin with metronome-marketplace. To assign different roles for different environments, consider naming those roles something like metronome-marketplace-production, metronome-marketplace-staging.
AWS review
  1. Add the role’s ARN value in Metronome.
      • Find the role’s ARN value in AWS from the newly created role from the roles page. The ARN uses the format arn:aws:iam::<AWS_ACCOUNT_ID>:role/metronome-marketplace.
      • Back in Metronome, enter the role’s ARN value in the AWS ARN field on step 2 of the menu.
  2. Click Save.

​
Provision AWS Marketplace customers in Metronome​

When a customer agrees to your Marketplace listing, you will need to provision their account in Metronome with a Metronome Contract that reflects the full details of the contract/subscription they signed with you in the Marketplace and AWS identified as the billing provider on that Contract. To connect a customer to AWS and have Metronome begin metering their invoices to AWS on your behalf:
  1. Go to an existing customer’s detail page in Metronome or create a new customer at Customers > Add New Customer.
  2. Go to Settings > Available Integrations > AWS > Get Started.
  3. Enter the AWS customer ID , product code, and region.
    • 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.
    • You can find the product code in the AWS Marketplace Portal for the product you’ve set up.
    • The AWS customer ID is included in the token passed to the fulfillment URL associated with your Marketplace product. For details on decoding the token, refer to the AWS documentation and the section on customer setup.
    • The Hourly usage-based pricing (per-unit) checkbox must be selected if the product is configured as a “Usage-based pricing ” product in the Marketplace. If this is a contract with consumption product, leave this checkbox unselected.
  4. Create a new contract for the customer that matches the details of the contract they signed with you in the AWS Marketplace. Include any credits and commits the customer has as part of the contract. Learn how to provision contracts in Metronome.
  5. Under the Billing Configuration section of the configure contract flow, select AWS as the billing provider.
CAUTIONYou cannot add or change the billing provider after creating the contract.
  1. Alternatively, you can use the following endpoints to set up AWS as a customer’s billing provider and assign it to a contract
    • To set up a new customer configured with AWS Marketplace:
      • Call the create customer endpoint
      • In the request payload, include customer_billing_provider_configurations:
        • In the configuration property, specify aws_product_code, aws_customer_id, and aws_region. If the product is configured as a “Usage-based pricing ” product in the Marketplace, also specify aws_is_subscription_product
      {
  // ...
  "customer_billing_provider_configurations": [
    {
      "billing_provider": "aws_marketplace",
      "configuration": {
        "aws_customer_id": "<your AWS customer ID>",
        "aws_product_code": "<your AWS product code>",
        "aws_region": "<your AWS region>",
        "aws_is_subscription_product": true // only if the product is configured as a usage-based pricing product
      },
      "delivery_method": "direct_to_billing_provider"
    }
  ]
}
    • To configure an existing customer with AWS Marketplace:
      • Call the set customer billing provider configurations endpoint
      • In the request payload, include your configuration
        • In the configuration property, specify aws_product_code, aws_customer_id, and aws_region. If the product is configured as a “Usage-based pricing ” product in the Marketplace, also specify aws_is_subscription_product
      {
  // ...
  {
    "billing_provider": "aws_marketplace",
    "customer_id": "<your customer id>",
    "configuration": {
      "aws_customer_id": "<your AWS customer ID>",
      "aws_product_code": "<your AWS product code>",
      "aws_region": "<your AWS region>",
      "aws_is_subscription_product": true // only if the product is configured as a usage-based pricing product
    },
    "delivery_method": "direct_to_billing_provider"
  }
}
    • To set up a new contract with invoices metered to AWS Marketplace:
      • Call the create contract endpoint
      • In the request payload, include billing_provider_configuration:
      {
  // ...
  "billing_provider_configuration": {
    "billing_provider": "aws_marketplace",
    "delivery_method": "direct_to_billing_provider"
  }
}
After you set AWS as that customer’s billing provider and begin sending usage events, Metronome starts metering that customer’s calculated invoice totals to AWS on your behalf.

​
What Metronome meters to AWS​

When metering to AWS, Metronome sums up a customer’s total amount accrued across all contract invoices that have AWS set as the billing provider since the last metering request. Metronome sets the quantity for each metering record as the total dollar amount expressed in USD cents. If a customer purchased a commit or was offered a credit as part of their contract, Metronome meters like this:
  • Prepaid commits A contract in Metronome specifies a schedule over which the customer pays for their prepaid commit. Those inputs create one or more scheduled invoices. Metronome meters the amount the customer owes on the prepaid commit on the date associated with the service period of the scheduled invoice, not the created at date.
  • Credits As credits on a Metronome contract are not paid for, Metronome only meters overages reflected on invoice totals after the credit has been drawn down in its entirety.
  • Postpaid commits Metronome meters usage reflected on invoice totals throughout the duration of the contract. However, if the entirety of the postpaid commit isn’t consumed by the end of the contract, Metronome ignores the true-up invoice and doesn’t send it to the marketplace. This is because the true-up invoice isn’t finalized until after the Metronome grace period ends, at which point the metering endpoint for the marketplace has closed. This means you must handle the true-up in the marketplace directly.

​
Handling marketplace customer lifecycle events in Metronome and your app​

Metronome stops metering if it detects subscription changes due to marketplace lifecycle events, and updates the customer’s status in Metronome accordingly. However, you are responsible for ensuing that the customer’s status is correctly represented in your application and ending the customer’s contract in Metronome, if relevant. To end the customer’s contract in the Metronome app, go to the customer > click the contract > select the overflow menu > click Edit Contract End Date. To end the customer’s contract with the Metronome API, use the /contracts/updateEndDate endpoint.

​
Limitations of AWS Marketplace listings​

Billing through the AWS Marketplace has some 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 gets 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. Contact your AWS or Metronome representative for help. AWS Marketplace strictly enforces the end of a customer’s Marketplace contract or subscription. 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’s 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. Metronome’s integration with AWS Marketplace only supports invoices with a USD fiat currency. Metronome throws an error if you attempt to create a contract with AWS Marketplace set as the billing provider, and the rate card on the contract has a non-USD fiat currency. In the case where the contract is associated with other other invoices that are not in USD (for example, scheduled invoices associated with scheduled charges), only the USD invoices will be sent to AWS Marketplace.