/aws-marketplace-metering

name: aws-marketplace-metering
description: Deploys, queries, and debugs AWS Marketplace usage-based (PAYG) metering — the pipeline (ResolveCustomer, BatchMeterUsage, EventBridge via SAM) and querying/debugging metering records, statuses, failures, discrepancies. Covers Concurrent Agreements (CustomerAWSAccountId + LicenseArn), multi-product, CloudTrail Event History (90 days; never CloudTrail Lake), Seller Reports (Billed Revenue/Usage columns + CSV/SDDS parsing), existing-stack detection, metering region for BatchMeterUsage/MeterUsage (DisabledApiException), metered AMI/Container + IAM roles, where registration data lives (customer-profile table), legacy ProductCode + CustomerIdentifier, DuplicateRecord/CustomerNotSubscribed, bad LicenseArn. Also SCOPES adjacent asks — flat-rate/SaaS-Subscription "do I still meter", CCP included-units + overage, contract term/annual renewal, forecasting future bills/usage — with the right answer or a one-line redirect. Use for any BatchMeterUsage/ResolveCustomer or SaaS usage-billing question.
version: 2

AWS Marketplace Metering

Overview

Complete lifecycle management for AWS Marketplace usage-based metering:

• **Setup (SaaS PAYG)** — deploy a new serverless metering integration (SAM, ResolveCustomer, BatchMeterUsage, EventBridge).
• **Query** — find, inspect, debug, analyze existing metering submissions (CloudTrail Event History ≤90 days; Seller Reports for billed history).

Scope is SaaS Usage-based (PAYG). SaaS Contract, Contract with Consumption Pricing (CCP), and AMI/Container are out of scope — redirect to public AWS docs.

> **Recommended:** the AWS MCP server provides sandboxed execution and audit logging. > > ⚠️ **AI-generated output — review before production. This skill is executed by an AI agent and > can make mistakes.** Everything it generates (CloudFormation/SAM templates, Lambda handlers, > IAM policies, `deploy.sh`) and everything it deploys to a seller's AWS account MUST be treated > as a proposal to review, not a trusted artifact. Before any deployed stack carries PRODUCTION > metering traffic (real billing), the seller MUST: > > - **Thoroughly review every resource the skill created or changed** — templates, Lambda code, > IAM roles/policies (least-privilege, no unintended grants), tables/indexes, queues, alarms — > in their own account, and confirm it matches their intent and their org's standards. Metering > errors directly affect revenue (under- or over-billing), so this review is not optional. > - **Put the generated code through the seller's normal code review + change-management process** > (do not ship AI output straight to production), and > - **Run the full hands-on test plan** (`references/test-plan.md`) end-to-end and verify each > expected observable outcome BEFORE relying on the integration for real billing. > The skill SHALL surface this review-before-production expectation to the seller, and SHALL NOT > imply that a successful deploy means the integration is production-ready without this review + test.

Using this skill's packaged resources

The packaged `scripts/`, `assets/`, `references/` show how to **structure** a metering stack — a reference, NOT content to copy verbatim.

• **Get every seller-specific value from the seller** (product code, region(s), stage name, VMT tags, alarm actions/thresholds, retention/KMS) and fill the `TODO:` markers. If a required value is unknown, **ask** — do not assume. VMT is presence-based: the seller writes each usage row's `usageAllocations` (their real tags); the pipeline (aggregator) merges them and never invents tags (no `VmtEnabled`/`VmtTagAttribute` parameter).
• **Do not change the architecture or `awsmp-*` naming** (two-stack layout, table/GSI/event wiring are fixed). Sellers customize only the marked `TODO:` sections. A request that would break the architecture/naming is explained as a constraint, not silently accommodated.

Guardrail — where this skill's own files live (MCP vs local)

Before reading a reference or running a script, determine how the skill was loaded:

• **AWS MCP `retrieve_skill`:** the skill is NOT on the local filesystem — fetch each reference/script via `retrieve_skill` with the `file` parameter (e.g. `file="references/deployment-steps.md"`); do NOT `file_read` these paths.
• **Installed locally:** read/run files from the local skill dir via relative paths.

This applies only to the skill's own files; user data/session artifacts are always in the user's working directory.

Critical Facts (apply to ALL metering operations)

• **CustomerAWSAccountId** (not CustomerIdentifier) + **LicenseArn** per UsageRecord for new (Concurrent Agreements) products.
• **EventBridge** (not SNS) for subscription events — emitted only in us-east-1.
• **`ResolveCustomer`** resolves the buyer's `LicenseArn`, `customerAWSAccountId`, and `productCode` from the `x-amzn-marketplace-token` when the buyer is redirected from the Marketplace console to the SaaS registration site; the SaaS then collects additional registration data and persists it (the PII fields) in the **in-region customer-profile table** (the PII-free subscribers table gets only the CA identity + statuses + `registeredRegions`). It returns a **top-level `LicenseArn`** field — `CustomerIdentifier` is a **deprecated legacy field, null for new SaaS integrations** (do NOT use it and do NOT treat its value as the LicenseArn). It is a **regional** API, but the region is the **seller's free choice** — it does NOT have to match where the buyer uses the software, and it does NOT gate metering. `BatchMeterUsage` can be called in ANY supported region independently of where `ResolveCustomer` was called. It is NOT a us-east-1-only API (only the EventBridge subscription events like `License Updated` are us-east-1-only). It MUST be called from the account that PUBLISHED the SaaS product (else the token will not resolve). **The `x-amzn-marketplace-token` is NOT one-time-use — it is REUSABLE until