AWS Marketplace Vendor-Metered Tagging, Explained

AWS Marketplace vendor-metered tagging is an optional part of usage metering: the seller splits the quantity in its usage records across tags it defines, such as business unit or cost center, and the buyer activates those tags to view the charges by category. The price, the dimensions and the total usage stay as they were.

---

Umbrella buys Acme’s product through AWS Marketplace on a usage price, and Umbrella’s FinOps lead has a request: split those charges by business unit in Umbrella’s AWS bill, so each unit’s budget carries its own share. Nothing about the deal should change, only how the bill reads.

On AWS, that is a documented part of metering, called vendor-metered tagging, and it takes both companies. Acme decides which tags each unit of usage carries and sends them with its usage records. Umbrella activates those tags in its own Billing console, which Acme can’t reach. If either half is missing, the bill reads the way it always has.

This guide walks through both halves: what the seller sends, the limits AWS enforces, how to choose the tags with the buyer, what the buyer switches on, and how to send the tags through Fours.

What is AWS Marketplace vendor-metered tagging?

AWS Marketplace vendor-metered tagging is a way to split the usage you report into tagged buckets, so the buyer can view your charges by categories such as business unit, cost center or account. AWS says it helps sellers “give the buyer more granular insight into their software usage and can help them perform cost allocation.”

For a SaaS product, it rides on the call you already make. BatchMeterUsage “supports vendor-metered tagging”: you can “split the usage in a UsageRecord into buckets by including UsageAllocations, where each UsageAllocation has a set of Tags that you define.” AWS is explicit about what the tags leave alone: “Vendor-metered tagging doesn’t change the price, dimensions, or the total usage that you report.”

	Without tags	With vendor-metered tags
Price	Your price per unit	The same
Dimensions	The dimensions on your product	The same
Usage reported	One quantity per dimension in each record	The same quantity, split across allocations that add up to it
What the buyer sees	Each dimension as its own line item, with total units and total cost	The same line items, plus each tag the buyer activates, to slice costs by

Tags travel on usage records, so they split what you meter. On a SaaS contract, AWS says “you only meter for usage beyond a customer’s contract entitlements,” so a contract buyer’s split reaches that metered usage and nothing else. Say so before the buyer plans a chargeback around it.

What does the seller send?

A usage allocation is one tagged bucket inside a usage record: an AllocatedUsageQuantity and the set of tags that quantity belongs to. The seller sends the same usage record as before, with a UsageAllocations list of them added, one entry per combination of tags.

AWS describes the change as one of aggregation: “Sellers can aggregate the metering records for resources with the same set of tags instead of aggregating usage for all resources.” Resources that share a tag set fold into one entry: in AWS’s own example, two resources with the same AccountId and BusinessUnit tags are “combined into a single UsageAllocations entry.” Resources without tags can go together in one allocation of their own.

Here is an illustrative record for a product priced per user, with the customer, license and timestamp fields left out. Forty users that hour: 25 in payments, 10 in risk, and 5 nobody has assigned yet.

{
  "Dimension": "users",
  "Quantity": 40,
  "UsageAllocations": [
    {
      "AllocatedUsageQuantity": 25,
      "Tags": [
        { "Key": "BusinessUnit", "Value": "payments" },
        { "Key": "CostCenter", "Value": "cc-1001" }
      ]
    },
    {
      "AllocatedUsageQuantity": 10,
      "Tags": [
        { "Key": "BusinessUnit", "Value": "risk" },
        { "Key": "CostCenter", "Value": "cc-2002" }
      ]
    },
    {
      "AllocatedUsageQuantity": 5,
      "Tags": [
        { "Key": "BusinessUnit", "Value": "unassigned" },
        { "Key": "CostCenter", "Value": "unassigned" }
      ]
    }
  ]
}

The allocations sit inside the usage record, so each record carries its own split. If you call BatchMeterUsage yourself, build each hour’s split before you send it. AWS deduplicates “per product/customer/hour/dimension” (per license instead of product, for Concurrent Agreements products), says multiple requests for the same customer, dimension and hour “are not aggregated,” and once you report a buyer’s usage of a dimension, “you cannot amend the record.” A second request can’t add allocations to an hour, and a mis-tagged hour stays mis-tagged.

What limits does AWS set on vendor-metered tags?

Five tags, 2,500 allocations in a record’s UsageAllocations list and 1 MB per request, plus validations every allocation has to pass. The seller guide lists them:

Rule	What AWS says
Tags	“Number of tags – 5”, and “Maximum tags across UsageAllocation list – 5”
Allocations	“Size of UsageAllocations (cardinality) – 2,500”
Request size	“Maximum request size – 1 MB”, counting “input attribute keys (for example, UsageRecords, AllocatedUsageQuantity, tags)”
Characters	Tag keys and values may use a-zA-Z0-9+ -=._:\/@
Unique tag sets	Two allocations “can’t have the same tags (that is, the same combination of tag keys and values)”; merge them into one
The sum	The allocated quantities “must equal the UsageQuantity, which is the aggregate usage”

Read the tag limit as a budget for your whole taxonomy. AWS states it “across” the allocation list, so plan on five keys at most, used the same way on every allocation.

Two of the rules have their own errors in the BatchMeterUsage reference: InvalidTagException, “The tag is invalid, or the number of tags is greater than 5,” and InvalidUsageAllocationsException, “Sum of allocated usage quantities is not equal to the usage quantity.” Both mean the data is wrong, not the service, so fix the record before you send it again. They sit beside the rest of the metering errors, and the 25-record cap every call already has, in when usage records fail.

Two of the limits pull against each other. Every allocation adds bytes, and AWS counts keys as well as values toward the 1 MB, so a record with a long allocation list leaves room for fewer records in the call. AWS’s method is to “create a sample request object with a maximum size based on the business requirement, convert the object into a JSON string, and obtain the size in bytes.” In its example, if one usage record can reach 200 KB, a request carries no more than five.

Cardinality multiplies across your keys. Two keys with 50 values each can produce 2,500 combinations, the whole allowance for one record. Tagging per user, which AWS describes as a common use case for a buyer with “numerous users” on one subscription, fits only while the users in a record stay within that allowance.

How do you choose the tags?

Start with the buyer, not your schema: AWS’s advice is to “first ask your buyers what they want to see in their cost allocation,” then split usage “across properties that you track for the buyer’s account.” Its examples are Account ID, Business Unit and Cost Centers. A tag earns its place only if the buyer’s finance team already allocates by it and your product can attribute usage to it.

Tags are not dimensions. A dimension decides what the buyer pays for, and changing one after launch reaches every agreement, as designing metering dimensions explains; a tag decides only how the buyer reads the bill. A buyer who wants charges split by team needs a tag, not a new dimension.

Settle these with the buyer’s billing owner before you write any code:

1. What do you allocate costs by? Business unit, cost center, department, AWS account, project or environment. Pick five keys at most, and keep the key names the same for every buyer who asks, so one integration serves them all.
2. Can our product tell which one each unit of usage belongs to? If the buyer’s cost centers aren’t in your product, the buyer’s admin needs somewhere to set them, per workspace or project, before any tag can be right.
3. What exact names and values? Keys reach the buyer’s reports as aws:marketplace:isv: followed by your key name, and values arrive as you send them, so agree on spelling and case. The values end up in the buyer’s billing data, so use identifiers their finance team recognizes.
4. What happens to usage nobody owns? It still counts toward the record’s total, so it needs an allocation. AWS lets you send untagged usage as one allocation; an explicit value such as unassigned makes the gap visible as a line the buyer can chase. Through Fours, use the explicit value, since each allocation in its documented request carries tags. Tell the buyer which you’ll use.
5. From when? Tags are fixed once a record is reported, so agree on a start date. If you start sending before the buyer activates, they can backfill earlier months.
6. Who will activate them? Someone in the buyer’s AWS account who can open Cost allocation tags in the Billing console. Send them the steps in the next section.

How does the buyer turn the tags on?

A vendor-metered tag is your tag key with the prefix aws:marketplace:isv:, and the buyer’s cost reports show it once someone in their account activates it as an AWS-generated cost allocation tag. A tag with the key BusinessUnit appears as aws:marketplace:isv:BusinessUnit. These are AWS’s steps for the buyer, worth pasting into your note to their billing owner:

1. Sign in to the AWS Management Console, open the AWS Billing console, and choose Cost allocation tags in the left navigation pane.
2. Choose the AWS-generated cost allocation tags tab.
3. Search for aws:marketplace:isv: to find the tags for every product that supports vendor-metered tagging.
4. Select the check boxes for the tags to activate, then choose Activate.
5. Optionally, to backfill tags for metering records reported before activation, choose Backfill tags, select the month the records were reported, then choose Confirm.

Set expectations on timing. AWS says activated tags “take up to 24 hours to appear in the Billing and Cost Management console and AWS Cost Explorer Service,” and a backfill “also takes approximately 24 hours to complete.”

In AWS’s simplified example of the buyer’s Cost and Usage Report, each allocation is its own row, with a column for each activated tag. Laid out the same way, without the product code and buyer account columns, the illustrative record above would read:

UsageDimension	UsageQuantity	aws:marketplace:isv:BusinessUnit	aws:marketplace:isv:CostCenter
users	25	payments	cc-1001
users	10	risk	cc-2002
users	5	unassigned	unassigned

In AWS Cost Explorer, the tags let the buyer “interactively slice costs by any tag.” AWS’s own example groups costs by a per-user tag across two dimensions, where “the seller defines a $0.00 dimension to report credit consumption and a $0.01 dimension for overage charges,” so the buyer sees which users consumed credits and which incurred overage.

How do you send vendor-metered tags through Fours?

Add the optional usageAllocations field to the usage you POST to the Fours Metering API: a map from each dimension key to an array of allocations, each with a quantity and its tags. Fours supports vendor-metered tagging for AWS Marketplace only, and the tags reach the buyer’s AWS Billing console, broken down by value, once the buyer activates them.

The same record, sent through Fours (illustrative values; the entitlement ID is a placeholder):

{
  "entitlementID": "your-entitlement-id",
  "records": {
    "users": 40
  },
  "usageAllocations": {
    "users": [
      {
        "quantity": 25,
        "tags": [
          { "key": "BusinessUnit", "value": "payments" },
          { "key": "CostCenter", "value": "cc-1001" }
        ]
      },
      {
        "quantity": 10,
        "tags": [
          { "key": "BusinessUnit", "value": "risk" },
          { "key": "CostCenter", "value": "cc-2002" }
        ]
      },
      {
        "quantity": 5,
        "tags": [
          { "key": "BusinessUnit", "value": "unassigned" },
          { "key": "CostCenter", "value": "unassigned" }
        ]
      }
    ]
  }
}

Three rules come with it:

• Key the allocations by dimension. Each key in usageAllocations is the metering dimension key you’re allocating, and its value is the list of allocations for that dimension.
• Make them add up. For each dimension, the quantity values must sum to that dimension’s total in the records map: 25 + 10 + 5 = 40 here.
• Plan within AWS’s limits. Each allocation’s tags are key-value pairs bound for the buyer’s AWS bill, so the five-tag cap and the character set above still apply.

The rest of the request is the usage you already report, and Fours validates, aggregates and reports it to the marketplace as before. The field reference and an example are in usage allocation with tags in Fours’ docs.

Frequently asked questions

What is AWS Marketplace vendor-metered tagging?

It’s an optional part of AWS Marketplace metering. The seller splits each usage record’s quantity across tags such as business unit or cost center, and the buyer activates those tags to view the charges by category. The price, dimensions and total usage don’t change.

Does vendor-metered tagging change what the buyer pays?

No. AWS says vendor-metered tagging “doesn’t change the price, dimensions, or the total usage that you report.” The buyer pays for the same usage at the same price; the tags only let them view that cost split by the categories you send.

How many tags can an AWS Marketplace usage record carry?

Five. AWS’s limits are five tags, 2,500 entries in a record’s UsageAllocations list and 1 MB per request. Each allocation needs a unique combination of tag keys and values, and the allocated quantities must add up to the record’s total usage.

How does a buyer activate vendor-metered tags?

In the AWS Billing console, they open Cost allocation tags, choose the AWS-generated cost allocation tags tab, search for aws:marketplace:isv:, select the tags and choose Activate. AWS says the tags take up to 24 hours to appear in the Billing and Cost Management console and Cost Explorer.

Can a buyer see tags on usage reported before they activated them?

Yes. When activating, the buyer can choose Backfill tags, select the month the metering records were reported and choose Confirm. AWS says the backfill takes approximately 24 hours, so tags you send before the buyer activates them aren’t wasted.

Can I send vendor-metered tags through Fours?

Yes, for AWS Marketplace. Add the optional usageAllocations field to your Fours Metering API request: a map from each dimension key to its allocations, each with a quantity and tags. Each dimension’s quantities must sum to its total in the records map.

Takeaways

• Vendor-metered tagging splits the usage you already report into tagged allocations. AWS says it doesn’t change the price, the dimensions or the total usage.
• AWS allows five tags, 2,500 allocations in a record and 1 MB per request. Every allocation needs a unique tag set, and the allocations must sum to the record’s total.
• Ask the buyer what their cost allocation needs to show before you build, and tag only with properties your product can attribute.
• The buyer activates the aws:marketplace:isv: tags under AWS-generated cost allocation tags. Allow up to 24 hours, and backfill earlier months if you were already sending tags.
• Through Fours, it’s one optional field, usageAllocations, on the metering request you already send, for AWS Marketplace.

Fours reports usage through one metering API across AWS, Microsoft, Google Cloud and Oracle, and on AWS Marketplace the buyer’s cost split travels on the same request. See how usage gets from your product to the marketplace bill in Fours’ billing and metering.