# Configuring custom metering for container products with AWS Marketplace Metering Service Configuring custom metering using AWS Marketplace Metering Service **Note** For Amazon EKS deployments, your software must use [IAM roles for service accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to sign the API call for the [https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html) API operation. Using [EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html), the node role, or long-term access keys are not supported. For Amazon ECS deployments, your software must use [Amazon ECS task IAM](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) role to sign the API call for the [https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html) API operation. Using the node role or long-term access keys are not supported. For Amazon Bedrock AgentCore Runtime deployments, your software must use the [AgentCore Runtime execution role](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-execution) to sign the API call for the [https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html) API operation. Long-term access keys are not supported. 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 [https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html) 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: + **Usage category** – The usage category helps buyers understand what your product is and how to use it. + **Unit type** – The unit type defines the unit of measure for billing. For example, bandwidth measured in GBps or MBps, the number of hosts, or data measured in MB, GB, or TB. + **Pricing dimensions** – The pricing dimensions represents a feature or service that you've set a per-unit price for (for example, users, scans, vCPUs, or deployed agents). Pricing dimensions are public. However, you can still define private and Bring Your Own License (BYOL) offers for public products. Don't send pricing in the metering records. You meter the quantity of units, and we use that along with the prices you defined when creating your product to compute the buyer's bill. If your product pricing doesn't fit with any of the predefined categories or unit types, you can choose the generic **Units** category. Then, use the dimension description to describe what the unit is. 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](https://catalog.workshops.aws/mpseller/en-US/container/integrate-custom) lab of the *AWS Marketplace seller workshop*. **Important** Free trial and prepaid entitlement are tracked on an hourly level. As a result, sending these records in separately might lead to the buyer being overcharged. **Topics** + [ ## Custom metering prerequisites ](#custom-metering-prereqs) + [ ## Testing `MeterUsage` integration for ECS and EKS ](#testing-meterusage-integration) + [ ## Testing MeterUsage integration for AgentCore ](#testing-agentcore-metering) + [ ## Error handling for `MeterUsage` ](#custom-metering-entitlement-error-handling) + [ ## (Optional) Vendor-metered tagging ](#container-vendor-metered-tagging) + [ ## Code example ](#container-meter-code-example) + [ # Integrating your container product using custom metering with the AWS Marketplace Metering Service and AWS SDK for Java ](java-integration-example-meterusage.md) ## Custom metering prerequisites Before publishing the product, you must do the following: 1. Create a new container product in the AWS Marketplace Management Portal, and make a note of its product code. 1. Use an AWS Identity and Access Management (IAM) role for the task, pod, or AgentCore Runtime endpoint running your application with the IAM permissions necessary to call `MeterUsage`. The IAM managed policy `AWSMarketplaceMeteringRegisterUsage` has these permissions. For more information about the policy, see [ AWSMarketplaceMeteringFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSMarketplaceMeteringFullAccess.html) in the *AWS Managed Policy Reference*. 1. (Optional) We recommend that you enable AWS CloudTrail logging in the task or pod definition if you want to see logging. 1. Make a test call to the `MeterUsage` API operation with a record for all of the pricing dimensions you define. ## Testing `MeterUsage` integration for ECS and EKS 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 use 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. **Note** If your product supports both Amazon ECS and Amazon EKS, you only need to launch in Amazon EKS for us to validate your integration. Test every dimension before launching your product to the public and after adding a new dimension. If you don't send a metering record for each dimension associated with a container product, it will result in an error with the request failing. 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. ## Testing MeterUsage integration for AgentCore 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 Bedrock AgentCore with the AWS account you use 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 Bedrock AgentCore agent 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 don’t need to aggregate hourly usage records. Call `MeterUsage` on every agent invocation with the usage for that invocation. You must use the latest released version of the AWS SDK for your language. This automatically populates the `ClientToken` parameter with an auto-generated value to help with idempotency. Prior releases of the SDK that do not populate this field will not work for `MeterUsage` calls from within Amazon Bedrock AgentCore. Due to a network issue, you must re-use the same exact request when retrying. Doing that ensures that the requests are treated idempotently. Due to differences in expected metering behavior between Amazon Bedrock AgentCore and other container products, we do not recommend sharing the same container image for use on Amazon Bedrock AgentCore and on Amazon ECS or EKS. ## Error handling for `MeterUsage` Call `MeterUsage` setting the `DryRun` parameter to true at container startup to validate that metering integration is working. 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 or AgentCore Runtime endpoint do not throw `CustomerNotSubscribedException`, even if the customer unsubscribes while the task or pod is still running. Those customers are still charged for running containers after they unsubscribe, and their usage is tracked. See [MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html) in the *AWS Marketplace Metering Service API Reference*for 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. ## (Optional) Vendor-metered tagging 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. **Note** Vendor-metered tagging is not supported for metering requests for Amazon Bedrock AgentCore products. You have several ways to tag a buyer's software usage. One 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/costmanagement/](https://console.aws.amazon.com/costmanagement/)). 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 `UsageAllocations` buckets. Each bucket represents the `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**. ![\[Diagram showing how vendor metering tags combine usage data. Three resources (Resource 1, 2, and 3) with different AccountIds and BusinessUnits are consolidated into a single Metering Record with UsageAllocations grouped by AccountId and BusinessUnit before being sent to the AWS Marketplace Metering Service.\]](http://docs.aws.amazon.com/marketplace/latest/userguide/images/seller-vendor-meter-tag.png) 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: + Number of tags – 5 + Size of `UsageAllocations` (cardinality) – 2,500 Validations include: + Characters allowed for the tag key and value – a-zA-Z0-9\$1 -=.\$1:\$1/@ + Maximum tags across `UsageAllocation` list – 5 + Two `UsageAllocations` can't have the same tags (that is, the same combination of tag keys and values). If that's the case, they must use the same `UsageAllocation`. + The sum of `AllocatedUsageQuantity` of `UsageAllocation` must equal the `UsageQuantity`, which is the aggregate usage. ### 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](#container-vendor-metered-tag-seller) example). **Cost Usage Report (Simplified)** | ProductCode | Buyer | UsageDimension | UsageQuantity | `aws:marketplace:isv:AccountId ` | `aws:marketplace:isv:BusinessUnit` | | --- | --- | --- | --- | --- | --- | | xyz | 111122223333 | Network: per (GB) inspected | 70 | 2222 | Operations | | xyz | 111122223333 | Network: per (GB) inspected | 30 | 3333 | Finance | | xyz | 111122223333 | Network: per (GB) inspected | 20 | 4444 | IT | | xyz | 111122223333 | Network: per (GB) inspected | 20 | 5555 | Marketing | | xyz | 111122223333 | Network: per (GB) inspected | 30 | 1111 | Marketing | For a code example, see [`MeterUsage` code example with usage allocation tagging (Optional)](#container-meterusage-code-example). ## 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](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html) in the *AWS Marketplace Metering Service API Reference*. ### Example response ``` { "MeteringRecordId": "string" } ``` # Integrating your container product using custom metering with the AWS Marketplace Metering Service and AWS SDK for Java Java integration example AWS Marketplace container products can have custom metering on up to 24 different pricing dimensions per product. To enable custom metering, you 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 [https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html) API operation. The following example outlines an implementation that uses the AWS SDK for Java to integrate with the [AWS Marketplace Metering Service](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html) `MeterUsage` operation. For complete details, see [`MeterUsage` Java examples](#meterusage-java-example). Many of the following steps apply regardless of the language. **Example: AWS Marketplace Metering Service integration** 1. Sign in to the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/tour). 1. From **Assets**, choose **Containers** to start creating a new container product. Creating the product generates the product code for the product to integrate with your container image. For information about setting AWS Identity and Access Management (IAM) permissions, see [AWS Marketplace metering and entitlement API permissions](iam-user-policy-for-aws-marketplace-actions.md). 1. Download the public [AWS Java SDK](https://aws.amazon.com/sdk-for-java/). **Important** To call the metering API operations from Amazon Elastic Kubernetes Service (Amazon EKS), you must [use a supported AWS SDK](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts-minimum-sdk.html) and run on an Amazon EKS cluster running Kubernetes 1.13 or later. 1. Call the `MeterUsage` operation from the task or pod once every hour for each dimension usage. The API operation accepts one metering record for a unique combination of `Dimension`, `Resource`, and `Hour`. The resource is either an Amazon Elastic Container Service (Amazon ECS) task or an Amazon EKS pod. ``` { "ProductCode" : "string", // (required) "UsageDimension" : "string", // (required) "UsageQuantity": int, // (optional) Default is 0. Acceptable value from [0, 2147483647 (INT_MAX)] "Timestamp": Date, // (required) Timestamp in UTC. Value can be one hour in the past. "UsageAllocations": List // (optional) UsageAllocations across 1 or more tags. } ``` **Note** It is possible to see transient issues in connecting to the AWS Marketplace Metering Service. AWS Marketplace strongly recommends implementing retries for up to 30 minutes, with exponential back off, to avoid short-term outages or network issues. 1. Rebuild a new version of your container image that includes the `MeterUsage` call, tag the container, and push it to any Docker registry that is compatible with Amazon ECS or Amazon EKS, such as Amazon Elastic Container Registry (Amazon ECR). If you are using Amazon ECR, ensure that the account launching the Amazon ECS task or Amazon EKS pod has permissions on the Amazon ECR repository. Otherwise, the operation fails. 1. Create an [IAM](https://aws.amazon.com/iam/) role that grants permission for your container to call `MeterUsage`, as defined in the following code example. You must supply this AWS Identity and Access Management (IAM) role in the [Task Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_role_arn) parameter of the Amazon ECS task or Amazon EKS pod definition. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "aws-marketplace:MeterUsage" ], "Effect": "Allow", "Resource": "*" } ] } ``` ------ 1. Create an Amazon ECS task or Amazon EKS pod definition that references the container that has integrated with AWS Marketplace and references the IAM role that you created in step 6. If you want to see logging, enable AWS CloudTrail logging in the task definition. 1. Create an Amazon ECS or Amazon EKS cluster to run your task or pod. For more information about creating an Amazon ECS cluster, see [Creating a cluster](https://docs.aws.amazon.com/AmazonECS/latest/userguide/create_cluster.html) in the *Amazon Elastic Container Service Developer Guide*. For more information about creating an Amazon EKS cluster (using Kubernetes version 1.1.3.x or later), see [Creating an Amazon EKS Cluster](https://docs.aws.amazon.com/eks/latest/userguide/create_cluster.html). 1. Configure the Amazon ECS or Amazon EKS cluster and launch the Amazon ECS task definition or Amazon EKS pod that you created in step 8, in the us-east-1 AWS Region. It's only during this testing process, before the product is live, that you have to use this Region. 1. When you get a valid response from `MeterUsage` for each of the dimensions being published for the product, you can begin creating your container product. For questions, contact the [AWS Marketplace Seller Operations](https://aws.amazon.com/marketplace/management/contact-us/) team. ## `MeterUsage` Java examples The following code examples use the AWS SDK for Java and AWS Marketplace Metering Service to call the `MeterUsage` operation. The following code example calls the `MeterUsage` operation without any `UsageAllocations`. ``` import com.amazonaws.services.marketplacemetering.AWSMarketplaceMetering; import com.amazonaws.services.marketplacemetering.AWSMarketplaceMeteringClientBuilder; import com.amazonaws.services.marketplacemetering.model.MeterUsageRequest; import com.amazonaws.services.marketplacemetering.model.MeterUsageResult; import java.util.Date; public class MeterUsage { private static final String PRODUCT_CODE = "......."; private final AWSMarketplaceMetering awsMarketplaceMetering; public MeterUsage() { awsMarketplaceMetering = AWSMarketplaceMeteringClientBuilder.standard().build(); } /** * Submits metering record for a FCP Dimension. The API accepts 1 metering record per dimension * for a given buyer's resource for a given timestamp hour. Ex. If a buyer is running 10 tasks, * the API will accepts 1 call to MeterUsage in an hour for a given dimension for each running task. * * @param dimension - FCP dimension name provided during the publishing of the product. * @param quantity - FCP dimension consumption value for the hour. * @param timestamp - Timestamp, in UTC, for which the usage is being reported. * Timestamp cant be more than 1 hour in the past. * Make sure the timestamp value is not before the start of the software usage. */ public void callMeterUsage(String dimension, int quantity, Date timestamp) { MeterUsageRequest meterUsageRequest = new MeterUsageRequest() .withProductCode(PRODUCT_CODE) .withUsageDimension(dimension) .withUsageQuantity(quantity) .withTimestamp(timestamp); MeterUsageResult meterUsageResult = awsMarketplaceMetering.meterUsage(meterUsageRequest); } } ``` The following code example calls the `MeterUsage` operation with `UsageAllocations`. ``` private static String callMeterUsageWithAllocationsByTag(AWSMarketplaceMetering marketplaceMetering) { // Tag Keys for the product String tagKey1 = "Key1"; String tagKey2 = "Key2"; String tagKey3 = "Key3"; // 1st Usage Allocation bucket which has two Tags [{Key1, Key1Value1},{Key2, Key2Value1}] List tagsForUsageAllocation1 = Arrays.asList(new Tag().withKey(tagKey1).withValue("Key1Value1"), new Tag().withKey(tagKey2).withValue("Key2Value1")); UsageAllocation usageAllocation1 = new UsageAllocation() .withTags(tagsForUsageAllocation1) .withAllocatedUsageQuantity(20); // 2nd Usage Allocation bucket which has two Tags [{Key1, Key1Value2},{Key2, Key2Value1}] List tagsForUsageAllocation2 = Arrays.asList(new Tag().withKey(tagKey1).withValue("Key1Value2"), new Tag().withKey(tagKey2).withValue("Key2Value1")); UsageAllocation usageAllocation2 = new UsageAllocation() .withTags(tagsForUsageAllocation2) .withAllocatedUsageQuantity(20); // 3rd Usage Allocation bucket which has two Tags [{Key1, Key1Value2},{Key2, Key2Value2},{Key3, Key3Value1}] List tagsForUsageAllocation3 = Arrays.asList(new Tag().withKey(tagKey1).withValue("Key1Value2"), new Tag().withKey(tagKey2).withValue("Key2Value2"), new Tag().withKey(tagKey3).withValue("Key3Value1")); UsageAllocation usageAllocation3 = new UsageAllocation() .withTags(tagsForUsageAllocation3) .withAllocatedUsageQuantity(15); // 4th Usage Allocation bucket with no tags UsageAllocation usageAllocation4 = new UsageAllocation() .withAllocatedUsageQuantity(15); List usageAllocationList = Arrays.asList(usageAllocation1, usageAllocation2, usageAllocation3, usageAllocation4); MeterUsageRequest meterUsageRequest = new MeterUsageRequest() .withProductCode("TestProductCode") .withUsageDimension("Dimension1") .withTimestamp(new Date()) //UsageQuantity value must match with sum of all AllocatedUsageQuantity .withUsageQuantity(70) .withUsageAllocations(usageAllocationList); MeterUsageResult meterUsageResult; try { meterUsageResult = marketplaceMetering.meterUsage(meterUsageRequest); } catch (Exception e) { // Log Error throw e; } return meterUsageResult.getMeteringRecordId(); } ```