Configuring custom metering for AMI products with AWS Marketplace Metering Service

The AWS Marketplace Metering Service is a pricing and metering feature that you can use to directly charge for your software by usage category. There are five usage categories: users, data, bandwidth, hosts, or unit. You can use the Metering Service with Amazon Machine Image (AMI)-based, container-based, and software as a service (SaaS)-based products. The following sections provide more information about how to configure custom metering with AWS Marketplace Metering Service.

The AWS Marketplace Metering Service enables several new scenarios. For example, if your software monitors hosts, you can charge for each host monitored. You can have different prices based on the host size, and charge for the number of concurrent hosts monitored each hour. Similarly, if your software allows many users across an organization to sign in, you can charge by the number of users. Each hour, the customer is charged for the total number of provisioned users.

For more information, see the AWS Marketplace Metering Service API Reference.

For more information about integrating AWS Marketplace Metering Service API for AMI-based products with custom metering pricing, see the List AMI products priced by custom units lab of the AWS Marketplace seller workshop.

Requirements

All AMI-based software that uses the Metering Service must meet the following requirements:

Call AWS Marketplace Metering Service

Your software must call the Metering Service hourly and record the consumption value for that hour.

When your software starts, it should record the minute-of-the-hour at which it started. This is referred to as the start-minute. Every hour on the start-minute, your software must determine the consumption value for that hour and call the Metering Service. For information about how to obtain this value, see Modifying your software to use the Metering Service.

To wake up each hour at the start-minute, your software must use one of the following approaches:

In addition, your software must call an in-Region AWS Marketplace Metering Service endpoint. Your product must have a correct Regional endpoint set up, so us-east-1 sends records to a us-east-1 endpoint, and us-west-2 sends records to a us-west-2 endpoint. Making in-Region calls provides buyers with a more stable experience and prevents situations in which an unrelated Region’s availability could impact software running in another Region.

When you send metering records to the service, you must connect to the AWS Marketplace Metering Service in your Region. Use the getCurrentRegion() helper method to determine the Region in which the EC2 instance is running, and then pass this Region information to the MeteringServiceClient constructor. If you don't specify an AWS Region in the SDK constructor, the default us-east-1 Region is used. If your application attempts to make cross-Region calls to the service, the calls are rejected. For more information, see Determining an Application’s Current Region and getCurrentRegion().

Failure handling

Your product must send metering records to the service, a public internet endpoint, so that usage can be captured and billed. Because it's possible for a customer to modify network settings in a way that prevents your metering records from being delivered, your product should account for this by choosing a failure mode.

Typically, software can fail open (provide a warning message but maintain full functionality) or fail closed (disable all functionality in the application until a connection has been reestablished). You can choose to fail open, closed, or something specific to your application. We strongly recommend that you refrain from failing closed after less than two hours of metering failures.

As an example of failing partially open, you could continue to allow access to the software but not allow the buyer to modify the software settings. Or, a buyer could still access the software but would not be able to create additional users. Your software is responsible for defining and enforcing this failure mode. Your software’s failure mode must be included when your AMI is submitted, and it can't be changed later.

Limitations

Keep these limitations in mind when designing and submitting your Metering Service-enabled software:

Code example

The following code example is provided to help you integrate your AMI product with the AWS Marketplace APIs required for publishing and maintaining your product.

MeterUsage with usage allocation tagging (Optional)

The following code example is relevant for AMI products with consumption pricing models. The Python example sends a metering record with appropriate usage allocation tags to AWS Marketplace to charge your customers for pay-as-you-go fees.

# NOTE: Your application will need to aggregate usage for the 
#       customer for the hour and set the quantity as seen below. 
#       AWS Marketplace can only accept records for up to an hour in the past. 
#
# productCode is supplied after the AWS Marketplace Ops team has 
# published the product to limited

# Import AWS Python SDK
import boto3
import time

usageRecord = [
    { 
        "AllocatedUsageQuantity": 2, 
        "Tags": 
            [ 
                { "Key": "BusinessUnit", "Value": "IT" },
                { "Key": "AccountId", "Value": "123456789" },
            ]

    },
    { 
        "AllocatedUsageQuantity": 1, 
        "Tags": 
            [ 
                { "Key": "BusinessUnit", "Value": "Finance" },
                { "Key": "AccountId", "Value": "987654321" },
            ]

    }
]

marketplaceClient = boto3.client("meteringmarketplace")

response = marketplaceClient.meter_usage(
    ProductCode="testProduct",
    Timestamp=int(time.time()),
    UsageDimension="Dimension1",
    UsageQuantity=3,
    DryRun=False,
    UsageAllocations=usageRecord 
)

For more information about MeterUsage, see MeterUsage in the AWS Marketplace Metering Service API Reference.

Example response

{ "MeteringRecordId": "string" }