Configuring custom metering for container products with AWS Marketplace Metering Service

AWS Marketplace container products can have custom metering on up to 24 different pricing dimensions per product. Each dimension can have a long-term contract price associated with it. To enable custom metering, integrate your container product with AWS Marketplace Metering Service. You can define your own pricing units and custom metering for that usage to AWS for billing using the MeterUsage API operation. The following sections show you how to configure custom metering for your container product.

Price dimensions are defined in two locations, once when creating your product in the AWS Marketplace Management Portal (seller portal) and once in your software to perform the MeterUsage operation. This two-factor method ensures that the subsequent offers are working as intended before they're made available to the public.

To set up custom metering, you'll need to choose the usage category, the unit type, and pricing dimensions:

Optionally, you may distribute the usage into allocations by properties that you track. The allocations are represented as tags to the buyer. These tags allow the buyer to view their costs split into usage by tag values. For example, if you charge by the user, and users have a "Department" property, you could create usage allocations with tags that have a key of "Department", and one allocation per value. This does not change the price, dimensions, or the total usage that you report, but allows your customer to view their costs by categories appropriate to your product.

We recommend that you send a metering record every hour. However, you can aggregate usage over daily or monthly periods as well. If you experience an outage, you can aggregate buyer software use and send it in the following hours metering. You can't send more than one record per hour.

For more information about integrating AWS Marketplace Metering Service API for container products with custom metering pricing, see the Integrate with custom metering lab of the AWS Marketplace seller workshop.

Custom metering prerequisites

Before publishing the product, you must do the following:

Testing MeterUsage integration

Use the MeterUsage operation to test your integration before submitting your image to AWS Marketplace for publishing.

Call MeterUsage from the container images by running your product on Amazon Elastic Container Service (Amazon ECS) or Amazon Elastic Kubernetes Service (Amazon EKS) with the AWS account you are using to list the product on AWS Marketplace. Your metering integration must dynamically set the AWS Region, rather than hard coding it. However, when testing, launch at least one Amazon ECS task or Amazon EKS pod containing your paid container in the US East (N. Virginia) Region so that the AWS Marketplace operations team can verify your work with the logs in that Region.

You can't fully test the integration until your product is published with all the required metadata and pricing information. If requested, the AWS Marketplace catalog operations team can verify receipt of your metering records.

Error handling for MeterUsage

If your container image integrates with the MeterUsage operation and receives an exception other than ThrottlingException at container startup, you should terminate the container to prevent unauthorized use.

Exceptions other than ThrottlingException are thrown only on the initial call to MeterUsage. Subsequent calls from the same Amazon ECS task or Amazon EKS pod do not throw CustomerNotSubscribedException even if the customer unsubscribes while the task or pod is still running. These customers are still charged for running containers after they unsubscribe and their usage is tracked.

See MeterUsage in the AWS Marketplace Metering Service API Referencefor detailed descriptions of common errors for MeterUsage. Each AWS SDK programming language has a set of error handling guidelines that you can refer to for additional information.

Vendor-metered tagging (Optional)

Vendor-metered tagging helps Independent Software Vendors (ISVs) give the buyer more granular insight into their software usage and can help them perform cost allocation.

There are many ways to tag a buyer's software usage. One way is to first ask your buyers what they want to see in their cost allocation. Then you can split the usage across properties that you track for the buyer’s account. Examples of properties include AccountId, Business Unit, Cost Centers, and other relevant metadata for your product. These properties are exposed to the buyer as tags. Using tags, buyers can view their costs split into usage by the tag values in their AWS Billing Console (https://console.aws.amazon.com/billing/). Vendor-metered tagging doesn't change the price, dimensions, or the total usage that you report. It allows your customer to view their costs by categories appropriate to your product.

In a common use case, a buyer subscribes to your product with one AWS account. The buyer also has numerous users associated with the same product subscription. You can create usage allocations with tags that have a key of AccountId, and then allocate usage to each user. In this case, buyers can activate the AccountId tag in their Billing and Cost Management console and analyze individual user usage.

Seller experience

Sellers can aggregate the metering records for resources with the same set of tags instead of aggregating usage for all resources. For example, sellers can construct the metering record that includes different buckets of UsageAllocations. Each bucket represents UsageQuantity for a set of tags, such as AccountId and BusinessUnit.

In the following diagram, Resource 1 has a unique set of AccountId and BusinessUnit tags, and appears in the Metering Record as a single entry.

Resource 2 and Resource 3 both have the same AccountId tag, 2222, and the same BusinessUnit tag, Operations. As a result, they're combined into a single UsageAllocations entry in the Metering Record.

Sellers can also combine resources without tags into a single UsageAllocation with the allocated usage quantity and send it as one of the entries in UsageAllocations.

Limits include:

Validations include:

Buyer experience

The following table shows an example of the buyer experience after a buyer activates the AccountId and BusinessUnit vendor tags.

In this example, the buyer can see allocated usage in their Cost Usage Report. The vendor-metered tags use the prefix “aws:marketplace:isv”. Buyers can activate them in the Billing and Cost Management, under Cost Allocation Tags, AWS-generated cost allocation tags.

The first and last rows of the Cost Usage Report are relevant to what the Seller sends to the Metering Service (as shown in the Seller experience example).

For a code example, see MeterUsage code example with usage allocation tagging (Optional).

Code example

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

MeterUsage code example with usage allocation tagging (Optional)

The following code example is relevant for container 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" }