canonical: https://jentic.com/apis/amazonaws.com/marketplace-metering

# AWS Marketplace Metering Service

Jentic publishes the only available OpenAPI specification for AWS Marketplace Metering Service, keeping it validated and agent-ready. The Metering API lets AWS Marketplace sellers submit usage records for paid products billed through AWS - SaaS, AMI, and container offerings priced by hourly, monthly, or custom dimensions. MeterUsage submits per-instance usage; BatchMeterUsage reports usage for SaaS subscriptions across multiple customers; ResolveCustomer turns a registration token into a customer identifier; RegisterUsage handles entitlement-based container products.

## For AI agents

Submit Marketplace usage records for SaaS, AMI, and container products and resolve customer identifiers from registration tokens.

## Scope

Does not handle product listing, customer subscription management, or invoicing - use for submitting usage records and resolving customer tokens for AWS Marketplace billing only.

## Capabilities

- Submit hourly usage records for AMI products with MeterUsage
- Batch submit usage records for multiple SaaS customers with BatchMeterUsage
- Resolve a customer registration token into a customer identifier and product code
- Register entitlement usage for paid container products through RegisterUsage
- Specify custom usage dimensions defined on the Marketplace product listing
- Support estimate-only requests for testing without recording billable usage
- Operate per-region in any region where AWS Marketplace metering is supported

## Use cases

### SaaS Subscription Metering

SaaS sellers on AWS Marketplace meter customer usage on custom dimensions (active users, storage GB, API calls) and submit usage with BatchMeterUsage, which accepts up to 25 customer records per call. Each record specifies the customer identifier returned from ResolveCustomer, the dimension name, and the quantity. AWS aggregates these records and bills the buyer through their AWS account.

Example prompt: Call BatchMeterUsage with ProductCode='abc123' and a UsageRecords array of 25 customer entries each specifying CustomerIdentifier, Dimension='active_users', Quantity, and Timestamp

### AMI Hourly Billing

AMI sellers run MeterUsage from instances of their paid product to record hourly usage on dimensions like 'small', 'medium', or feature flags. The call comes from inside the AMI itself, signed with the IAM role attached to the instance, and reports the dimension consumed in the previous hour. Marketplace handles aggregation, taxation, and customer billing.

Example prompt: Call MeterUsage from an EC2 instance with ProductCode, Timestamp set to the start of the previous hour, UsageDimension='medium', and UsageQuantity=1

### Customer Registration Resolution

When a buyer subscribes to a SaaS product on Marketplace, AWS redirects them with a registration token. The seller's web app exchanges that token for the persistent customer identifier and product code via ResolveCustomer, then stores the identifier so future BatchMeterUsage calls reference the correct buyer. The exchange is one-time and idempotent per token.

Example prompt: Call ResolveCustomer with the RegistrationToken passed in the marketplace redirect, then store the returned CustomerIdentifier and ProductCode in our user database

### AI Agent Billing Operations

Billing agents call Marketplace Metering through Jentic to submit usage records on a schedule, retry transient failures, and reconcile counts against internal usage stores. Jentic isolates the AWS keys and exposes the four metering operations as discoverable tools so the agent can answer 'submit yesterday's user counts to Marketplace' without learning the AWS SDK.

Example prompt: Search Jentic for 'submit marketplace usage', load BatchMeterUsage, and execute it with the previous day's customer-by-customer counts on dimension 'active_users' grouped from internal usage logs

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /#X-Amz-Target=AWSMPMeteringService.MeterUsage | Submit per-instance usage record for an AMI product |
| POST | /#X-Amz-Target=AWSMPMeteringService.BatchMeterUsage | Submit a batch of usage records for SaaS customers |
| POST | /#X-Amz-Target=AWSMPMeteringService.ResolveCustomer | Exchange a registration token for a customer identifier |
| POST | /#X-Amz-Target=AWSMPMeteringService.RegisterUsage | Register entitlement usage for a paid container product |

## Key resources

- **MeterUsage** — Submit per-instance usage records for AMI products
- **BatchMeterUsage** — Submit batched usage records for SaaS subscriptions
- **ResolveCustomer** — Exchange a registration token for a customer identifier
- **RegisterUsage** — Register usage for paid container product entitlements

## Why Jentic

- **Setup:** Wiring the AWS Marketplace Metering Service by hand means implementing Signature Version 4 signing, resolving the regional metering.marketplace host, and building the X-Amz-Target action headers yourself. Through Jentic you install once, import Marketplace Metering from the API Directory, store the AWS keys once, and your agent calls it.
- **Permission scoping:** Marketplace Metering is a JSON action API where usage records and customer tokens travel in the request body, so scope the agent to the operations it needs, such as MeterUsage and ResolveCustomer. You choose the operations it may call, so usage submission cannot drift into broader account access.
- **Credential handling:** Your AWS access keys are stored once, encrypted, by your own Jentic One instance and each request is signed with Signature Version 4 at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit marketplace usage' or 'resolve a marketplace customer token', and Jentic returns the matching Metering operation with its input schema, including the UsageRecords shape required by BatchMeterUsage, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AWS Marketplace Catalog Service** — Catalog defines the products and dimensions Metering reports against
- **AWS License Manager** — License Manager governs entitlements that Metering may report usage against
- **Stripe** — Stripe Billing handles usage-based billing outside AWS Marketplace

## FAQ

### Why is there no official OpenAPI spec for AWS Marketplace Metering?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AWS Marketplace Metering Service via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AWS Marketplace Metering API use?

The API uses AWS Signature Version 4 (HMAC) with an access key ID and secret access key scoped via IAM. AMI sellers typically call from instances using an instance-profile role with aws-marketplace:MeterUsage permissions; SaaS sellers call from server-side workloads. Through Jentic, those credentials live in the encrypted vault and are signed in server-side.

### Can I submit usage for multiple customers in a single call?

Yes. BatchMeterUsage accepts up to 25 UsageRecords in one call, each containing CustomerIdentifier, Dimension, Quantity, and Timestamp. The response surfaces successful records and a separate UnprocessedRecords array - the seller is expected to retry unprocessed entries with backoff.

### What are the rate limits for the AWS Marketplace Metering API?

AWS does not publish hard request-per-second limits in this spec, but BatchMeterUsage caps at 25 records per call and per-region throttles apply to high-volume submitters. Submit usage hourly or daily and batch records to stay well within service limits.

### How do I submit SaaS usage through Jentic?

Search Jentic for 'submit marketplace usage' to surface BatchMeterUsage. Load the schema with the Jentic SDK (pip install jentic), execute it with your ProductCode and the array of UsageRecords for each metered customer, and inspect the Results and UnprocessedRecords fields in the response.

### Is the AWS Marketplace Metering API free?

Yes - submitting metering records has no API fee. AWS Marketplace charges sellers a percentage of revenue on the underlying products being metered, but the metering calls themselves do not incur a usage charge.

### Can I limit what my agent is allowed to do with the AWS Marketplace Metering API?

Yes. Because your Jentic One instance is self-hosted, you decide which of the four metering operations your agent may call and which AWS credentials it may use. If your agent only needs to record usage, you can allow MeterUsage and BatchMeterUsage while withholding ResolveCustomer and RegisterUsage, so usage submission never drifts into broader account access. You set these rules, and they are enforced server-side when each request is signed.