> **aws-marketplace-metering** — skill 61 of 132 in [aws/agent-toolkit-for-aws](https://skillsdocs.com/aws/agent-toolkit-for-aws). > > Book (all skills, one file): https://skillsdocs.com/aws/agent-toolkit-for-aws.md > Machine manifest: https://skillsdocs.com/aws/agent-toolkit-for-aws/.well-known/agent-skills/index.json > Install the book: `npx skills add aws/agent-toolkit-for-aws` > Upstream: https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/SKILL.md @ `main` > Raw bytes, no header: https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/SKILL.md > Base for relative paths: https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/ > Licence: Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html > > Bundled files (30), referenced from this skill's directory: > - `assets/requirements.txt` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/assets/requirements.txt > - `assets/template-events.yaml` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/assets/template-events.yaml > - `assets/template-main.yaml` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/assets/template-main.yaml > - `references/architecture.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/architecture.md > - `references/client-side-guardrails.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/client-side-guardrails.md > - `references/concurrent-agreements.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/concurrent-agreements.md > - `references/deployment-steps.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/deployment-steps.md > - `references/dimension-reference.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/dimension-reference.md > - `references/existing-sellers.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/existing-sellers.md > - `references/iam-credentials.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/iam-credentials.md > - `references/query-path.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/query-path.md > - `references/query-patterns.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/query-patterns.md > - `references/registration-page.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/registration-page.md > - `references/scalable-metering-design.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/scalable-metering-design.md > - `references/seller-reports.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/seller-reports.md > - `references/setup-path.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/setup-path.md > - `references/test-plan.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/test-plan.md > - `references/troubleshooting.md` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/references/troubleshooting.md > - `scripts/aggregator.py` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/scripts/aggregator.py > - `scripts/cleanup.py` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/scripts/cleanup.py > - `scripts/deploy.sh` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/scripts/deploy.sh > - `scripts/deprovision_cleanup.py` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/scripts/deprovision_cleanup.py > - `scripts/discoverer.py` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/scripts/discoverer.py > - `scripts/expiry.py` — https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/main/skills/specialized-skills/aws-marketplace-skills/aws-marketplace-metering/scripts/expiry.py > - …and 6 more, listed in https://skillsdocs.com/api/v1/books/aws/agent-toolkit-for-aws/skills/aws-marketplace-metering > > Content © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request --- 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: 1 --- # 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 it expires (~4 hours)**: re-resolving the same token before expiry returns the same result, so a buyer who errored on the registration page can retry with their original link while it is still within the ~4h window. After expiry `ResolveCustomer` returns `ExpiredTokenException` (an already-consumed/invalid token returns `InvalidTokenException`) and the buyer re-clicks "Set up your account" for a FRESH token (no resubscribe). A retry days later = expired token → mint a new one. (`references/troubleshooting.md`.) - **DuplicateRecord** = first-write-wins and REPORTED (`Status = DuplicateRecord`, not `Success`); the original quantity stays billed. A resubmit with a *different* quantity is NOT billed (under-billing risk). Safe only for an *identical* retry — never a way to correct a quantity; never call it "benign". - **CustomerNotSubscribed** = real failure, do NOT retry. Causes: (1) invalid identifier, (2) agreement ended/expired, (3) buyer account suspended. - **A bad `LicenseArn` is a REQUEST-level `InvalidLicenseException` that fails the ENTIRE `BatchMeterUsage` batch** — NOT a per-record `Status` in `Results` (unlike `CustomerNotSubscribed`). Mitigation: shape-validate the LicenseArn client-side before batching (reason `InvalidLicenseArn`) so a malformed ARN never enters a batch, and on a request-level `ClientError` bisect-and-retry to isolate the poison record so its co-batched records still meter. - **`BatchMeterUsage` (SaaS) is REGIONAL, but the SELLER CHOOSES the region — there is NO `InvalidEndpointRegionException`.** Call it in the region where usage occurs (the seller's choice; nearest supported region for on-prem/other-cloud); deploy a stack per metering region; dedup is per region. It is supported in MOST commercial regions but not all — where the API is unavailable in a chosen region the call returns **`DisabledApiException`** (meter in a supported region instead). There is **no** `InvalidEndpointRegionException` for SaaS `BatchMeterUsage`; the seller picks the region and per-region dedup makes multi-region metering correct, not an error. - **Do NOT conflate this with AMI/Container `MeterUsage`.** Metered **AMI/Container** products are OUT OF SCOPE for this skill (redirect to public docs), and their region rule is the OPPOSITE: **`MeterUsage` MUST be called in the SAME region as the running EC2 instance / ECS task — you CANNOT call it from us-east-1 (or any other region) regardless of where the instance runs; a mismatched region returns `InvalidEndpointRegionException`.** Such products authenticate with an **IAM instance/task role** (EC2 instance profile, ECS task role, or EKS IRSA), never embedded/long-lived access keys. This same-region enforcement + `InvalidEndpointRegionException` applies ONLY to AMI/Container `MeterUsage`, NOT to SaaS `BatchMeterUsage`. See the [public AWS docs](https://docs.aws.amazon.com/marketplace/latest/userguide/) for AMI/Container metering. - **Dimension validity is server-authoritative.** The pipeline is NOT configured with a dimension list and does NOT reject client-side; an undefined dimension fails the `BatchMeterUsage` call with a REQUEST-level `InvalidUsageDimensionException` (case-sensitive, not billed) — it is NOT a per-record `Results[].Status`. The pipeline isolates the offending record by bisection (depth-bounded to ⌈log2(batch size)⌉ = 5 so a many-failure batch can't overload the submitter), marks it `RejectedClientSide` (reason = the exception name), and emits the `BatchMeterUsageException` metric. Adding/renaming a catalog dimension needs no redeploy. - **Rejection reason codes come in a client-side ↔ server-side PAIR — always surface BOTH.** A row can be rejected two ways and the rubric expects the named code for each: (1) the pipeline's **client-side guardrail** rejects the row BEFORE the API call and stamps a client-side reason code (`MalformedTimestamp`, `InvalidLicenseArn`, `TooManyTags`, `InvalidDimension`, etc.), marking it `RejectedClientSide` and emitting `UsageRecordRejected`; (2) if a row reaches the API and is rejected there, the **server-side** equivalent is the matching `BatchMeterUsage` request-level exception (`TimestampOutOfBoundsException`, `InvalidLicenseException`, `TooManyTagsException`, `InvalidUsageDimensionException`). When explaining any rejection, name BOTH the client-side reason code AND its server-side exception equivalent, not just one. Client-side reasons ↔ server-side exceptions: `MalformedTimestamp` ↔ `TimestampOutOfBoundsException`; `InvalidLicenseArn` ↔ `InvalidLicenseException`; `TooManyTags` ↔ `TooManyTagsException`; `InvalidDimension` ↔ `InvalidUsageDimensionException`. - **`UnprocessedRecords` = a PARTIAL-BATCH outcome, NOT "the call accepted the record."** The `BatchMeterUsage` request did NOT fail completely: records that succeeded appear in `Results`, records that failed to process appear in `UnprocessedRecords` (**not billed; typically TRANSIENT** — `ThrottlingException` / `InternalServiceException`). They are **safe to re-submit** because metering is idempotent (first-write-wins dedup on `CustomerAWSAccountId + LicenseArn + dimension + hour`, per region). The deployed submitter **RETRIES the record ONCE**; if it still fails it is **left for reprocessing and picked up on the NEXT SCHEDULED run** (`rate(5m)`) — NOT a blind client-side retry loop; the persistent case is alarmed via `UsageRecordUnprocessed`. This is DISTINCT from: **per-record `Results[].Status` verdicts** (`Success` / `CustomerNotSubscribed` / `DuplicateRecord` — FINAL, do NOT blindly retry), and **request-level exceptions** (`InvalidUsageDimensionException` / `TimestampOutOfBoundsException` / `InvalidLicenseException`) that fail the ENTIRE batch and require isolating the poison record by bisection. - **CloudTrail is regional** — query the same region BatchMeterUsage is called in. **~15 min** delivery latency. **90-day** retention (recommend Seller Reports for older). Use CloudTrail **Event History** (default, no setup) filtered on `eventSource = metering-marketplace.amazonaws.com` — **never CloudTrail Lake / `create-event-data-store`** for metering lookups. - **Timestamp window = 24 HOURS** (not 1h), measured from `now`; a record whose timestamp is older than 24h is **outside the window and REJECTED — it is NOT submitted.** Concretely, a **30-hour-old** record is past the 24h boundary and does **NOT** fall inside the window: server-side it fails the call with `TimestampOutOfBoundsException` and one bad timestamp rejects the ENTIRE batch; before it ever reaches the API the pipeline's client-side guardrail rejects the row with reason code **`MalformedTimestamp`** (marked `RejectedClientSide`, not billed) so a stale/out-of-window timestamp never enters a batch. Do NOT tell a seller a >24h (e.g. 30h) record is "within the window" or "should be submitted" — it is rejected; the only exception is the 6-hour month-boundary grace, which accepts *previous-month* records until 06:00 UTC on the 1st. The pipeline meters only COMPLETED hours in `now-23h … now-1h` (never the in-progress/current hour — that is only metered by a deprovisioning flush), **oldest-first**, gated by `MeteringLockHours`; a skipped/failed hourly-discoverer or `rate(5m)`-submitter run self-recovers on a later run while the hour is still in the 24h window. Detail: `references/scalable-metering-design.md`. - **Best practice — submit usage within ~1 hour of generation.** Late submission is a TOP real-world failure mode: the closer a row gets to the 24h boundary the less retry headroom it has, and past 24h it is permanently lost (`TimestampOutOfBounds`, not billed). Write/submit usage promptly (well inside the window) rather than batching a day's worth at the edge. - **Age-out is TERMINAL and clears the pending marker.** When a row/aggregation cannot be metered before it exceeds the 24h window, the pipeline ages it out: it sets a **terminal `meteringStatus` (`AggregationExpired` for a raw row that never aggregated, `SubmissionExpired` for an aggregated row never submitted)** AND **CLEARS `meteringPending`** so the row drops off the sparse `metering_pending` GSI and the discoverer's oldest-first backward walk STOPS returning it (no infinite re-processing). These fire the `UsageAggregationExpired` / `UsageSubmissionExpired` alarms — a paged signal that usage silently never metered; investigate the writer/pipeline delay. - **A ~1-hour-old timestamp should NOT normally get `TimestampOutOfBoundsException`** — 1h is well inside the 24h lookback, so this is UNUSUAL. Do NOT tell the seller to "just wait until HH:05". The real cause is almost always (a) **one bad record failing the WHOLE batch** (a co-batched malformed/out-of-window/undefined-dimension record makes the request-level exception reject every record in the call until it is isolated) or (b) **clock skew** (an unsynchronized host stamping timestamps in the future / far past, or local time instead of UTC). Fix: **inspect the batch for the malformed record** (bisect to isolate it) and verify the writer's clock is NTP-synced and stamping whole-second UTC. - **Current (in-progress) hour is NEVER metered on the normal path.** The pipeline only submits COMPLETED hours (`now-23h … now-1h`); the hour currently in progress stays open and is skipped until it completes. `MeteringLockHours` (default **1**, validated 1..20) is how many hours an hour stays open for late usage before it is aggregated/submitted — with the default of 1, the pipeline processes the just-completed hour. Pending hour-buckets are drained **OLDEST-FIRST** so the oldest usage is submitted before it approaches the 24h boundary and ages out (`TimestampOutOfBounds`). The aggregator collapses each `(licenseArn, customerAWSAccountId, dimension, hour)` group to **exactly ONE `BatchMeterUsage` record per hour** (metering is per-group-per-hour, first-write-wins). The ONLY time the current in-progress hour is metered is the deprovisioning final-usage flush (lock-bypassed, see the event model). So "why isn't this hour showing usage yet?" = it is still the current hour and/or still inside `MeteringLockHours` — expected, not a bug. - **`BatchMeterUsage` limits are TWO independent caps: ≤25 UsageRecords AND ≤1 MB request payload.** A batch with 25 VALID records can still be rejected for SIZE if the serialized request exceeds 1 MB (large/many `usageAllocations` tag-sets, long ARNs) — it is the byte size, not the record count. Fix: put fewer records per call so each request stays under 1 MB. (The submitter already coalesces ≤25 per call; a size rejection means those records are too large — split further.) - **VMT (vendor metered tagging) tag limit = 5 `usageAllocations` tags per UsageRecord.** A usage row may carry at most **5 tags** in its `usageAllocations`; more than 5 is invalid. The pipeline's client-side guardrail rejects the over-tagged row BEFORE the API call with reason code **`TooManyTags`** (marked `RejectedClientSide`, not billed, emits `UsageRecordRejected`); the server-side equivalent if such a row reached the API is **`TooManyTagsException`**. When asked about the VMT tag cap, name BOTH the 5-tag maximum AND the `TooManyTags` client-side rejection (not just the number). VMT is presence-based — the seller supplies the tags; the pipeline never invents them. - **VMT is ALL-OR-NOTHING per group — do NOT mix tagged and untagged rows.** Within one `(licenseArn, customerAWSAccountId, dimension, hour)` group, either EVERY non-zero row carries `usageAllocations` or NONE does. Mixing allocated and unallocated non-zero rows in the same group is **NOT allowed** — the pipeline rejects it client-side with reason code **`MixedAllocatedAndUnallocated`** (`RejectedClientSide`, not billed). It is NOT "partial VMT attribution." Zero-quantity rows are ignored for this check, and DIFFERENT groups in the same hour/batch may independently have or omit allocations. Also per group: each row's `AllocatedUsageQuantity` values must sum to that row's `quantity`, and ≤2500 merged tag-sets per UsageRecord (else `AllocationSumMismatch` / `TooManyAllocations`). Detail: `references/setup-path.md`, `references/client-side-guardrails.md`. - **Metering is idempotent (first-write-wins dedup per `CustomerAWSAccountId + LicenseArn + dimension + hour`, per region)**, and the pipeline is DECOUPLED — there is no single meter Lambda and **no "reserved concurrency = 2"** knob. The **submitter** (the ONLY stage that calls `BatchMeterUsage`) runs **`ReservedConcurrentExecutions=1` — a single SERIAL submitter**, deliberately serial to stay within the `BatchMeterUsage` request-rate limit (**documented quota: 10 requests/second per account per region**; `MeterUsage` 10/s, `RegisterUsage` 5/s — see [service quotas](https://docs.aws.amazon.com/marketplace/latest/developerguide/metering-service-quotas.html)) and avoid `ThrottlingException`. The **discoverer** runs at reserved concurrency **30**; the **aggregator** and **cleanup** scale via their **SQS event-source-mapping `MaximumConcurrency`**. **SQS absorbs bursts** — throughput comes from **draining the queues**, not from raising submitter concurrency. If a seller needs higher sustained metering TPS, **contact AWS Marketplace Seller Operations** rather than raising concurrency past a safe level. - **`ThrottlingException` handling — exponential backoff WITH JITTER.** On `ThrottlingException` (or a throttled `UnprocessedRecords`), retry with **exponential backoff plus JITTER** (randomized delay — name jitter explicitly; do NOT use a fixed/synchronized retry interval, which re-collides). Keep each call within the **≤25-record (and ≤1 MB)** limit — do not grow the batch to "catch up." Retries are SAFE because metering is **idempotent (first-write-wins)**: a re-sent already-billed record simply comes back as **`DuplicateRecord`** with the original quantity still billed. Do NOT treat `DuplicateRecord` as a reason to avoid retrying a throttled/unprocessed record — it is the idempotency guarantee that MAKES retry safe (the only caveat is never resubmit the same group with a DIFFERENT quantity, which would not be billed). - **Registration form data (PII) lives in a per-Region `customer-profile` table, NOT the subscribers table.** The in-region register Lambda writes the allowlisted registration/KYB fields to `awsmp--customer-profile` (PK `licenseArn`, SK `customerAWSAccountId`, seller-requested GSIs) IN the Region it runs in, keeping buyer PII in-region. The profile row is **ALWAYS upserted for a registered buyer — even with ZERO extra form fields** (the row keyed by identity is always written). The unified subscribers table (us-east-1) is **PII-FREE** — the register Lambda writes only the non-PII `productCode` + an idempotent `registeredRegions` append (NO registration form data) — plus the CA identity (`licenseArn`, `customerAWSAccountId`, `agreementId`) and the two lifecycle statuses — so it is safe in us-east-1 even for opt-in-Region products. The template ALWAYS sets the register Lambda's `CUSTOMER_PROFILE_TABLE` env; if it is unset that is a MISCONFIGURATION and the handler **fails loud (HTTP 500)** rather than silently skipping the PII write. (An existing seller's own registration handler may store data differently — the skill adapts and does not force this reference Lambda verbatim.) - **Legacy (pre-CA) integrations** may use `ProductCode` + `CustomerIdentifier` instead of `LicenseArn`. The skill does NOT impose its own template/fallback on them (it must NOT present a fixed `startswith("arn:")` fallback as its template) — it grounds legacy behavior in the seller's EXISTING integration + public AWS docs (`references/existing-sellers.md`). - **Free trials — behavior depends on WHICH model (do not give a blanket "always meter" answer); confirm the model first and ground specifics in the public docs ([SaaS free trials](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-free-trials.html), [PLG guide](https://aws.amazon.com/blogs/awsmarketplace/a-guide-to-executing-a-saas-product-led-growth-strategy-in-aws-marketplace/)):** - **AWS Marketplace SaaS free trial feature** (native, time-bound: the buyer subscribes to a separate trial offer and must upgrade before it ends): **meter normally throughout** — do NOT withhold. AWS applies the trial pricing so trial usage invoices at $0 (`$0` estimated revenue), and after conversion the same dimensions bill with **no integration change**. - **Embedded free tier / usage-based trial** (buyer on the STANDARD paid offer, seller decides when charges begin): WHEN/WHAT to meter is the seller's own pricing decision — the skill does NOT prescribe a metering strategy. For plain usage-based (PAYG) the default is **meter all billable usage** and let pricing/offers handle any free allowance. Billing only BEYOND a contract-included quantity is **Contract with Consumption (CCP)** — OUT OF SCOPE (see below) → [public docs](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-integrate-contract.html). - **Usage ingestion is the seller's responsibility.** The seller writes rows into the usage table (incl. cross-account collection if multi-account). In the default **full** mode the PIPELINE aggregates hourly; in **direct-submit** mode the seller supplies finalized hourly totals (see Q9). - **All timestamps are UTC** — the seller stamps the sort-key timestamp AND `meteringPending` in UTC; the GSI is queried by UTC hour bucket, so a local-time write mis-files/mis-meters the row silently. - **Audit timestamps (`createdAt`/`updatedAt`)** — every row the pipeline writes carries `createdAt` (write-once, `if_not_exists`) and `updatedAt` (refreshed each write), ISO-8601 whole-second UTC, applied uniformly via a shared stamp helper. These are **audit-only metadata and do NOT gate metering** — metering decisions follow **`subscriptionStatus` / the `metering_pending` GSI**, never `createdAt`/`updatedAt`. ## Concurrent Agreements (CA) — registration & metering model (recite when asked how CA works) All new SaaS products use Concurrent Agreements: identity is **`CustomerAWSAccountId` + `LicenseArn`** (never the legacy `CustomerIdentifier`). Explain these facts explicitly whenever a CA registration, event-ordering, attribution, or lookup question comes up: - **Registration → subscriber upsert is driven by the EventBridge `License Updated` event.** When a buyer subscribes, AWS Marketplace emits **`License Updated`** (us-east-1 only). The events-stack subscription Lambda consumes it and **UPSERTS the subscriber record** (keyed by `licenseArn` + `customerAWSAccountId`, with `agreementId`) setting **`agreementStatus=active`** and `subscriptionStatus=active` — this is what makes the buyer eligible to meter. `ResolveCustomer` (called from the branded registration page) resolves the token to `LicenseArn` + `customerAWSAccountId` + `productCode` and persists registration/PII to the in-region customer-profile table, but it is the **`License Updated` upsert (agreementStatus=active)** that establishes the metering-eligible subscriber row. Do not describe CA registration without naming the `License Updated` → `agreementStatus=active` upsert. - **`ResolveCustomer` DOES return the `LicenseArn` — the answer is YES.** `ResolveCustomer` resolves the `x-amzn-marketplace-token` and returns a **top-level `LicenseArn`** field, alongside `customerAWSAccountId` and `productCode`. Do NOT say `ResolveCustomer` does not return a LicenseArn — it does, at the top level of the response. `CustomerIdentifier` is a deprecated legacy field that is **null for new CA integrations** — do NOT use it or treat its value as the LicenseArn. (For a new SaaS product the `LicenseArn` from `ResolveCustomer` is the identifier you persist and later pass to `BatchMeterUsage`.) - **Eligibility is enforced at `BatchMeterUsage`, independent of event arrival order.** Metering eligibility is checked server-side by `BatchMeterUsage` at submit time against the current agreement/subscription state — it does NOT depend on the order in which EventBridge events arrived. If usage is submitted before the subscriber is active (or after the agreement ended) the record returns `CustomerNotSubscribed`; once `License Updated` has made the buyer active, the same record meters. So out-of-order or late-arriving events do not corrupt billing: `BatchMeterUsage` is the authority, and the row self-recovers on a later `rate(5m)` run while still inside the 24h window. Do not claim the pipeline gates metering on event ordering — it gates on eligibility at submit time. - **Metering is attributed PER LICENSE, not per account** — reinforce the usage-table key model. The raw usage table is **PK `licenseArn`, SK `customerAWSAccountId#dimension#timestamp`**. One AWS account (`customerAWSAccountId`) can hold MULTIPLE agreements/licenses, and dedup + billing are scoped to `CustomerAWSAccountId + LicenseArn + dimension + hour` — so usage is aggregated and metered **per `licenseArn`**, never collapsed to a single per-account total. When asked "meter per account or per license?" the answer is **per license** (the `licenseArn` is the partition key). - **The `metering_pending` GSI drives metering; the subscribers table is lifecycle-only.** Discovery of what to meter comes ONLY from the sparse **`metering_pending` GSI** on the usage/aggregated tables (HASH = `meteringPending` hour-bucket, RANGE = `licenseArn`, projecting `customerAWSAccountId` + `dimension`). The discoverer **PAGINATES** through the GSI — it runs a paginated `Query` (following `LastEvaluatedKey` across pages), NOT a single read — so an hour with more pending groups than one page still fully drains. The **subscribers table is NOT consulted to find usage to meter** — it holds only CA identity + the two lifecycle statuses (`agreementStatus` / `subscriptionStatus`) and is used for **lifecycle/deprovisioning** (is this license active? has it entered the deprovisioning flush?). Do not say the pipeline scans or queries the subscribers table to locate pending usage — that is the GSI's job. - **Unified subscribers table schema (us-east-1, PII-FREE):** **PK `licenseArn`, SK `customerAWSAccountId`**, with attributes `agreementId`, `agreementStatus`, `subscriptionStatus`, `productCode`, `registeredRegions`, `deprovisioningExpiry` (set only during a deprovisioning flush), and `createdAt`/`updatedAt` audit stamps. `registeredRegions` is a set updated **idempotently** (append via `ADD`, no duplicates) and is **reference-only — it NEVER gates metering**. It carries **NO registration form data / NO PII** (PII lives only in the in-region `customer-profile` table). A `customerAWSAccountId` GSI supports account-scoped lookups. **Why `licenseArn` is the PK (all THREE reasons):** (1) under Concurrent Agreements one buyer can hold MULTIPLE concurrent licenses for the same product; (2) using `customerAWSAccountId` as the PK would COLLAPSE those distinct agreements into one row (lost usage / double-billing); (3) each license has its own INDEPENDENT lifecycle and metering idempotency (dedup is per `CustomerAWSAccountId + LicenseArn + dimension + hour`), so per-agreement keying keeps them isolated. Name all three when asked why `licenseArn` is the partition key. - **ONE PRODUCT PER `BatchMeterUsage` CALL — do NOT mix products in one batch.** Every `UsageRecord` (every `LicenseArn`) in a single `BatchMeterUsage` request MUST belong to the **SAME product**. Mixing `LicenseArn`s from two different products in one call returns a request-level **`InvalidLicenseException`** and fails the ENTIRE request (nothing meters). Make a SEPARATE `BatchMeterUsage` call per product. Within that single-product batch you MAY combine different dimensions and different buyers/licenses of that one product; dedup remains per `CustomerAWSAccountId + LicenseArn + dimension + hour`, and the ≤25-record and ≤1 MB caps apply to the batch. (The deployed submitter already groups by product so it never co-batches products; a seller batching by hand must do the same.) - **Batch cap = ≤25 UsageRecords AND ≤1 MB** (two independent limits) — see the Critical Facts entry; a 25-record batch can still be rejected for the 1 MB payload size. So N licenses × M dimensions = N·M records ⇒ ⌈N·M/25⌉ sequential calls (e.g. 50 licenses × 2 dimensions = 100 records ⇒ 4 calls, submitted serially). **Retry behavior:** any records returned in `UnprocessedRecords` (transient `ThrottlingException`/`InternalServiceException`, not billed) are **retried** — the deployed submitter retries once then re-drives them on the next scheduled run — because metering is idempotent (first-write-wins); do not drop them. - **The events stack (EventBridge + subscribers table) is in us-east-1 only — the metering (main) stack can live in ANOTHER region.** Marketplace subscription events (`License Updated`, `License Deprovisioned`, etc.) are emitted ONLY in us-east-1, so the shared events stack and its PII-free subscribers table are pinned to us-east-1 (co-located with the consumer subscription Lambda). But the **per-region main/metering stack (usage table + pipeline Lambdas + `BatchMeterUsage`) is deployed in whatever region(s) the seller meters from** — only the events+subscribers stack is pinned to us-east-1. When the metering region ≠ us-east-1 the pipeline reads the subscribers table cross-region; if the seller meters in us-east-1 too, everything is single-region. ## Response Rules — MANDATORY 1. **Check Out of Scope FIRST** — if out of scope, decline in one sentence; do NOT proceed. 2. **KNOWLEDGE questions** (how do I, how does X work, which data source): answer from this skill; do NOT call AWS APIs/tools. 3. **ACTION questions** (deploy now, query now, run this): execute AWS commands — prefer the `shell` tool with AWS CLI over MCP `use_aws` for long-running ops. 4. **Multi-region/multi-product questions** are KNOWLEDGE — explain the architecture; do NOT deploy unless explicitly asked. 5. **"How do I find X" = KNOWLEDGE** — explain the method; execute only on "show me"/"run it". ## Out of Scope — Decline Immediately Respond ONLY with "This is outside the scope of AWS Marketplace metering" + a one-line redirect; do NOT call tools or load references: - Physical fulfillment / FBA / retail storefront → "Try Amazon Seller Central" - Personal AWS billing / cost management → "Try AWS Budgets or Cost Explorer" - Product listing/offer creation, Private Offers, offer/discount management → "Try AWS Marketplace Management Portal" - Pricing, contracts, EULA management → "Try Marketplace Catalog API docs" - **SaaS Contract / Contract with Consumption Pricing (CCP) — included-units, overage billing, AND contract lifecycle (term, renewal, expiry)** — OUT OF SCOPE for this usage-based (PAYG) skill. This covers BOTH: (a) a contract that INCLUDES N units/period and billing USAGE BEYOND it (e.g. "500 included API calls/month, buyer used 750 → 250 overage"), which is CCP / SaaS Contract + `GetEntitlement`-then-`BatchMeterUsage`-overage; AND (b) any **contract-term or renewal** question (e.g. "my customer's ANNUAL CONTRACT is renewing next week — do I change my metering setup?"). A contract term/renewal is a **SaaS Contract (entitlement) concern**, not a PAYG metering concern. Do NOT answer these from metering knowledge — in particular, do NOT tell the seller that a renewal just re-fires `License Updated` / needs no metering change, do NOT walk through the CCP overage flow, and do NOT describe entitlement checks. The skill does not own contract/entitlement behavior and must not assert how a contract renewal maps to metering events. Reply ONLY with the redirect: "SaaS Contract / Contract with Consumption Pricing — including contract terms, renewals, included units, and overage — is out of scope for this usage-based (PAYG) metering skill. Use the public AWS documentation: [Contract pricing](https://docs.aws.amazon.com/marketplace/latest/userguide/contract-pricing.html), [Contract pricing with consumption (CCP)](https://docs.aws.amazon.com/marketplace/latest/userguide/contract-pricing.html), [SaaS contract integration](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-integrate-contract.html), and [entitlements + renewals via GetEntitlements](https://docs.aws.amazon.com/marketplaceentitlement/latest/APIReference/API_GetEntitlements.html)." - **Flat-rate / SaaS Subscription products with NO usage metering — verifying a customer is still active/entitled** (e.g. "flat monthly subscription, no metering, how do I check customers are still active?"): this is subscription **entitlement** management (SaaS Subscriptions + `GetEntitlements` / entitlement EventBridge events), NOT usage-based (PAYG) metering. It is OUT OF SCOPE — do NOT design an active-customer check, describe `GetEntitlements`/entitlement-event handling, or repurpose this skill's metering subscriber table for it. Reply ONLY with the redirect: "A flat-rate SaaS Subscription with no usage metering is out of scope for this usage-based (PAYG) metering skill. Verifying active/entitled customers is done via AWS Marketplace SaaS entitlements — see the public AWS documentation: [SaaS subscriptions](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-customer-setup.html), [checking entitlements with GetEntitlements](https://docs.aws.amazon.com/marketplaceentitlement/latest/APIReference/API_GetEntitlements.html), and [subscription lifecycle events with EventBridge](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-eventbridge-integration.html)." - **Forecasting / predicting FUTURE bills or usage** (e.g. "forecast next month's customer bills from my CloudTrail metering trend", trend projection, revenue prediction): OUT OF SCOPE — this skill queries only HISTORICAL submissions (≤90-day CloudTrail) and billed history (Seller Reports); it does NOT forecast → "Forecasting future bills/usage is out of scope. This skill queries only historical metering submissions; for projections, hand the fetched CloudTrail/Seller-Reports data to your host agent/model for analysis, or use [AWS Cost forecasting](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-forecast.html) / your own analytics over [Seller Reports](https://docs.aws.amazon.com/marketplace/latest/userguide/reports-and-data-feed.html)." - AWS account billing disputes → "Contact AWS Support" - Anything not involving BatchMeterUsage, ResolveCustomer, metering records, or usage-based billing for SaaS/software. --- ## SETUP PATH — Deploy New Metering Integration Full walkthrough: `references/setup-path.md` + `references/deployment-steps.md`. ### Seller Questionnaire (ask ALL before generating code) - **Q1 Product code (or product ID).** Accept either; resolve a product ID to the code via the Catalog API (`describe-entity`) at validation. The dimension list is NOT a deploy input (dimension validity is server-authoritative); you may list dimensions for the seller's info only. **Recommend validating dimension NAMES against the catalog with the Marketplace Catalog API `DescribeEntity` (us-east-1)** before the seller wires them into usage rows — the returned entity details enumerate the product's registered dimension API names (case-sensitive). Confirming the seller's dimension strings match the catalog exactly at setup time is the way to avoid the runtime **`InvalidUsageDimensionException`** (an undefined/misspelled/wrong-case dimension fails the whole `BatchMeterUsage` call). This is a validation aid only — it does NOT make the dimension list a deploy input. - **Q2 Are you the ISV/seller?** Only the seller (publisher) or an authorized 3PI may integrate; a 3PI is out of scope — decline. Confirm publishing-account access. - **Q3 Which region(s) do you meter from?** Events stack is always us-east-1; deploy a main stack in EACH region where usage occurs and meter in-region. Dedup is per `CustomerAWSAccountId + LicenseArn + dimension + hour`, scoped to the submission region — do NOT funnel all usage into one region. [Region support](https://docs.aws.amazon.com/marketplace/latest/developerguide/metering-regions.html#batchmeterusage-region-support). - **Q4 Stage name (MANDATORY).** API Gateway stage (e.g. `v1`/`live`/`prod` — seller's choice). **No default, no fallback to `prod`**; deploy fails fast if empty. Pass via `STAGE_NAME`. - **Q5 Does a stack already exist for this product?** If yes → modify/extend: gather context and inspect the seller's existing stack (may use arbitrary naming) before changing anything — see `references/existing-sellers.md`. - **Q6 Metering lock hours** (`METERING_LOCK_HOURS` → `MeteringLockHours`, default 1, validated **1..20**). How many hours an hour stays open for late usage before it is aggregated/submitted (default 1 = process the just-completed hour). At the cap, an hour is first submitted at age 20, leaving ≥4h in the 24h billable window for retries/re-drive. **Month-aware:** previous-month hours keep the lock until 03:00 UTC on the 1st, then no-lock (submit each run) until the 06:00 UTC cutoff, and aren't aged out before then; a previous-month record written after 03:00 must already be pre-aggregated (else `DuplicateRecord`). - **Q7 TTL / retention** (per table, `deploy.sh` env vars; `0` disables): - Raw usage table `USAGE_TABLE_TTL_DAYS` (default 365) — RECOMMEND on (high-volume table). The seller's writer sets the `ttl` epoch attribute; the template only makes DynamoDB honor it. Floor ≥2 days that must exceed `MeteringLockHours`+24h so a row can't expire before metering. - Aggregated table `AGGREGATED_USAGE_TTL_DAYS` (default 0 = retain) — RECOMMEND omit/large (small billing audit trail). When >0 the submitter sets `ttl` only on `Success` rows. - Enabling TTL needs the deployer's `dynamodb:UpdateTimeToLive` (already in the policy). - **Q8 Create health dashboards?** (`CREATE_DASHBOARD`, default true). Per-product main-stack dashboard (per-Lambda Errors/Throttles/Invocations/Duration; queue/DLQ depth + oldest-age; EMF `UsageRecordRejected` by reason, `UsageRecordUnprocessed`, `CustomerNotSubscribed`, `BatchMeterUsageException` by exception, `UsageAggregationExpired`, `UsageSubmissionExpired`, `DuplicateRecord`) + a shared events-stack dashboard. Health-only; reflects the deployed mode (Q9); sellers can opt out / customize. - **Q9 Full pipeline vs direct-submit** (`DEPLOYMENT_MODE`, default `full`) — explain both so the seller chooses knowingly: - **full** — seller emits RAW per-second events; the skill deploys the raw `usage` table + discoverer→aggregator→cleanup→submitter→submission-expiry, and the pipeline aggregates each `(licenseArn, account, dimension, hour)` group to one `BatchMeterUsage` record/hour. Best when the seller doesn't already aggregate or wants platform-owned aggregation + client-side rejection visibility. - **direct-submit** — seller ALREADY produces finalized hourly totals; the skill deploys ONLY `aggregated_usage` + submitter + submission-expiry + register/subscription (smaller/cheaper). Seller writes finalized records straight to `aggregated_usage` (PK `licenseArn`, SK `customerAWSAccountId#dimension#hour`, `quantity`, `meteringPending`=hour bucket). - **Finalize-before-insert (direct-submit, critical):** any record in `aggregated_usage` MAY be submitted on the next 5-min run — write a record ONLY when FINAL for its group, because a second write returns `DuplicateRecord` and the later quantity is NOT billed. The seller owns upstream aggregation/idempotency here. - **Not a one-way door:** the seller can switch modes later (a stack UPDATE that adds/removes mode-specific resources; raw `usage` table is `Retain`). Call out the blast radius before flipping a live stack. - **Q10 Registration fields + profile lookups** (`ALLOWED_REGISTRATION_FIELDS`) — EXPLAIN first, then ask. The in-region register Lambda persists ONLY these allowlisted fields (each length-bounded; the token is never stored) as a **`registrationData` map** on the in-region **`customer-profile`** table (PK `licenseArn`, SK `customerAWSAccountId`) — buyer **PII stays in-region and OUT of the PII-free us-east-1 subscribers table**. Fields in the map are retrievable by the base key but NOT independently queryable. Ask: (a) which form fields to capture (incl. any KYB fields — name/email/company/use-case); (b) whether any field must be **looked up directly** (e.g. by `email`) — if so it is **promoted** to a top-level attribute + a **GSI** (ask HASH-only or HASH+RANGE per promoted field). Keep fields OPTIONAL/seller-confirmed; invent no PII; mask PII in logs. **Mapping `licenseArn`→the seller's internal SaaS tenant ID is the SELLER's responsibility** — anchor it on the subscribers table (`licenseArn` from `License Updated`, PII-free) and/or the customer-profile table (`licenseArn` captured at registration); add a `tenantId` attribute + GSI if lookup-by-tenant is needed (`references/architecture.md`). > **Product Type Gate:** after credentials, verify via the Catalog API the product is SaaS + usage-based (`ExternallyMetered`). AMI/Container/SaaS-Contract-only → out of scope, redirect to [public docs](https://docs.aws.amazon.com/marketplace/). > **Concurrent Agreements is the silent default** — all new products use `CustomerAWSAccountId` + `LicenseArn`; do NOT ask. A pre-existing legacy stack may use `ProductCode` + `CustomerIdentifier` — understand it before changing (`references/existing-sellers.md`). ### Setup ordering (do NOT skip or reorder) 1. Obtain ephemeral credentials (SSO → `sts assume-role`; never long-lived keys; don't ask for keys first). 2. Product type gate (SaaS + ExternallyMetered). 3. Product visibility gate — deploy/mutate the product-specific MAIN stack ONLY when the CURRENT product is `Limited`, never `Published` (provide code for the seller's own pipeline instead). Direct-deploy the main stack only when the current product is `Limited` AND there is no existing per-product stack (an existing one is modify/extend, seller-confirmed). The SHARED events stack is never redeployed/mutated when it already exists (it may serve other, possibly `Published`, products with live traffic — reuse its outputs); only the first onboarding creates it. See `references/existing-sellers.md`. 4. Confirm the questionnaire answers (incl. stage name). 5. Only THEN generate + deploy: **materialize the template(s) + Lambda handlers + `deploy.sh` in the seller's workspace and deploy THOSE on-disk files** (`sam build --template-file` + `sam deploy`) — never an inline/transient template. Modify/extend edits the seller's existing files in place (merge env vars). Leave all artifacts in the workspace afterward (code/stack parity; seller can version/re-deploy/develop, customizing only `TODO:` sections). 6. **EXISTING-STACK guardrails (ENFORCE, do not bypass).** WHEN a stack already exists for this scope, the skill SHALL NOT auto-apply changes: it SHALL (a) present the exact diff/change set for the seller's review, (b) require the seller's EXPLICIT confirmation and their normal CODE REVIEW + change-management process before applying, (c) scope changes to the CURRENT product's main stack, and (d) never redeploy/mutate the shared events stack that already serves other (possibly `Published`) products — reuse it. Direct auto-deploy is reserved for a `Limited` product with NO existing stack. See `references/existing-sellers.md`. 7. **After integration, run the full test plan.** At the END of setup/modify, the skill SHALL recommend and (where it can) walk the seller through the complete hands-on test plan (`references/test-plan.md`) — verifying every expected observable outcome — and SHALL state that the integration should not carry PRODUCTION billing traffic until that review + testing passes. A failure at any gate stops the workflow before deployment. ### Stack naming | Component | Pattern | Example | |-----------|---------|---------| | Events stack | `awsmp-events-stack` | Shared, us-east-1 | | Main stack | `awsmp--metering` | `awsmp-4ml54db8vrmjuykaw1psroool-metering` | | Events stack (staged) | `awsmp-events--stack` | `awsmp-events-beta-stack` | | Main stack (staged) | `awsmp---metering` | `awsmp-4ml54db8vrmjuykaw1psroool-beta-metering` | For a non-production sandbox, deploy stage-scoped stacks (the stage folds into every resource name) and set `MeteringMode=dry-run` so the submitter never calls the real `BatchMeterUsage` — use test accounts only. See `references/existing-sellers.md` / the setup path. ### Supported features SaaS Usage (PAYG) ✅ | Concurrent Agreements ✅ | VMT ✅ | Multi-region ✅ | Multi-product ✅ Out of scope (→ [public docs](https://docs.aws.amazon.com/marketplace/)): CCP, AMI/Container, SaaS-Contract-only (GetEntitlements), 3PI. > **Scale:** the pipeline is decoupled (discoverer → work queue → aggregator → aggregated-usage + cleanup queue → submitter) so it is designed to handle thousands of metering records per hour. Second-precision rows bound a group at ≤3600 rows/hour → supports high volume at ≤~1 write/sec per `(licenseArn, account, dimension)` group. For finer/higher rates, recommend a streaming ingestion tier (e.g. Kinesis Data Streams) that pre-aggregates to per-second/hour rows (public-knowledge/host-model-determined, not first-class to this skill). Full design: `references/scalable-metering-design.md`. > **GSI-driven discovery (never a Scan):** the discoverer finds pending usage via the sparse **`metering_pending` GSI — HASH = `meteringPending` hour-bucket (`YYYY-MM-DDTHH`), RANGE = `licenseArn`**, projecting **`customerAWSAccountId` + `dimension`** (INCLUDE/ALL, NOT `KEYS_ONLY`) so a query returns the `(licenseArn, customerAWSAccountId, dimension)` tuples directly — no follow-up read to discover the group. Each group is then read with a **targeted `begins_with` sort-key prefix** (`begins_with(customerAWSAccountId#dimension#timestamp, "{account}#{dimension}#{hourPrefix}")`), NOT a full `licenseArn`-partition query + timestamp `FilterExpression`. ### Deployment (summary; full steps in `references/deployment-steps.md`) 1. Generate SAM template + Lambda code (fill `TODO:`s). 2. Deploy events stack (us-east-1) — shared EventBridge + subscribers table. 3. Deploy main stack (seller's region) — Lambdas + DynamoDB + API Gateway + alarms. 4. Set the AMMP **Fulfillment URL** to the **branded registration page** (S3+CloudFront front-end that captures buyer/KYB fields and calls `RegistrationUrl`), NOT the raw `RegistrationUrl` (smoke-test fallback only) — manual seller step. See `references/registration-page.md`. 5. End-to-end test (subscribe → resolve → write a conforming usage row → discoverer → aggregator → submitter → verify `Aggregated` + `Success`). 6. Validate via CloudTrail logs. **After deploy, state the seller's ongoing responsibilities and guide the hands-on test** (`references/test-plan.md`): the stacks do nothing until the seller **writes conforming usage rows** — whole-second `customerAWSAccountId#dimension#timestamp` sort key (matching segments) and a `meteringPending` bucket that **equals the row's own UTC timestamp hour**. A **mis-stamped `meteringPending` is the ONE writer error the pipeline cannot detect** (silently never metered) — confirm via the test. Also: subscribe a notification to the alarms + watch the dashboards (`UsageRecordRejected` by reason, `BatchMeterUsageException` by exception, `CustomerNotSubscribed`, `UsageAggregationExpired`/`UsageSubmissionExpired`); catalog dimension changes need no redeploy. Several results are async (post-subscribe `License Updated` → `licenseArn`/`subscriptionStatus`; hourly discoverer + `rate(5m)` submitter/expiry) — **poll with bounded backoff**, or manually invoke a Lambda to exercise a path immediately (say which). **Recommend running the FULL test plan (`references/test-plan.md`) end-to-end at the end of the integration and verifying every expected observable outcome — plus a review of all created/changed resources — BEFORE the integration carries production billing traffic** (AI-generated output; see the review-before-production callout above). Prerequisites, credentials, and the full least-privilege deployer policy: `references/iam-credentials.md`. ### Event & status model (recite when asked how cancellation/metering works) Two INDEPENDENT status fields on the subscriber row (never conflate): - **`agreementStatus`** = `active`/`inactive` (agreement lifecycle). - **`subscriptionStatus`** = `active`/`deprovisioning`/`inactive` (license lifecycle; there is **no `deprovisioned` value**). Metering follows the LICENSE lifecycle only: - **`License Updated`** → agreement+subscription `active` (metering allowed). - **`License Deprovisioned`** → `subscriptionStatus=deprovisioning` + a `deprovisioningExpiry` (event time + ~1h); OPENS the ~1-hour final-usage flush window. **The lock-bypass mechanism:** during this window the pipeline submits ALL remaining pending usage for that license IMMEDIATELY, **ignoring `MeteringLockHours` and the normal completed-hours-only gate** — it does NOT wait for `MeteringLockHours` to elapse and it DOES meter the **current in-progress hour** (the one hour the normal path always skips). **Concrete mechanism/marker:** the `License Deprovisioned` handler sets `subscriptionStatus=deprovisioning` + `deprovisioningExpiry` on that subscriber row; the discoverer runs in a **flush-deprovisioning mode** that keys off that marker and enqueues the pending buckets (over `now-23h … now-1h` PLUS the current hour) for **only that license**, oldest-first. **The bypass is SCOPED to the deprovisioning license ONLY** — other active licenses keep the normal `MeteringLockHours` gate and completed-hours-only behavior; one buyer's deprovisioning never force-flushes another buyer's open hour. It is the deprovisioning flush that bypasses the lock, NOT a change to `MeteringLockHours` itself and NOT a `Purchase Agreement Ended` event. Once the window has elapsed, the events-stack **deprovision-cleanup** Lambda (rate(15m)) sets `inactive` and clears the deprovisioning markers — finalization is time-based, so it is correct across multiple hours and regions. After the server window closes, `BatchMeterUsage` returns `CustomerNotSubscribed`. - **`Purchase Agreement Ended`** → `agreementStatus=inactive` ONLY (does NOT change subscriptionStatus, stop metering, or flush). - **`Purchase Agreement Amended`** → refresh agreement metadata (stays active). - **`Purchase Agreement Created`** → NOT consumed by metering (no licenseArn); the seller handles it if needed (pre-provisioning, CRM), without activating metering. Do NOT invert these (`License Deprovisioned`, not `Purchase Agreement Ended`, opens the flush window). Do NOT discard queued records before flushing. `registeredRegions` is reference-only and NEVER gates metering. ### Setup references - Full walkthrough + writer contract + Common Mistakes + VMT/token/timestamp/schema/meter-flow: `references/setup-path.md` - Deployment steps: `references/deployment-steps.md` · IAM policy: `references/iam-credentials.md` - Concurrent Agreements + data model: `references/concurrent-agreements.md` · Architecture + status lifecycle: `references/architecture.md` - Existing sellers (modify/extend, legacy): `references/existing-sellers.md` - Branded buyer page + Know Your Buyer (KYB) capture: `references/registration-page.md` - Hands-on test plan (manual steps, scoped cases, async polling): `references/test-plan.md` - Monitoring & alarms: `references/troubleshooting.md` · Client-side guardrails (all checks before `BatchMeterUsage`): `references/client-side-guardrails.md` - Reference implementation: `scripts/metering_core.py` (shared) + `discoverer.py`/`aggregator.py`/`cleanup.py`/`submitter.py`/`expiry.py` (pipeline) + `register.py`/`subscription.py`; `scripts/test_event_publisher.py` (non-prod sandbox test-event generator, dry-run stages only); `scripts/deploy.sh` (needs `assets/requirements.txt`); SAM templates `assets/template-main.yaml`, `assets/template-events.yaml` ### Monitoring & alarms (seller-owned) The deployed stack creates `awsmp-*` metrics + CloudWatch alarms in the SELLER's account covering the revenue-loss signals (per-stage Lambda `Errors`/`Throttles` across discoverer/aggregator/cleanup/submitter/expiry, a "did not run" invocations alarm, `>24h` age-out, and the EMF business-status metrics). Alarms are always created; actions wire to an OPTIONAL in-region SNS topic (`AlertsTopicArn`). Business-status metrics use EMF from the Lambda logs (no extra runtime IAM). **Handling alarms is the seller's responsibility** — AWS Marketplace and this skill do not track client-side errors; neither the deployer nor any Lambda publishes to the topic (CloudWatch fires the action). Thresholds/actions/topic are seller `TODO:`s. Detail: `references/troubleshooting.md`. **"What alarms tell me metering records are being REJECTED / not metered?"** — the stack creates a dedicated alarm on each rejection/failure signal so a seller is paged the moment records stop metering (all fire into `AlertsTopicArn`; thresholds are seller `TODO:`s): - **`UsageRecordUnprocessed`** (alarm `*-usage-unprocessed`) — `BatchMeterUsage` returned `UnprocessedRecords` that were STILL unprocessed after the submitter's one automatic retry. The submitter does NOT raise on this (it leaves them pending for the next `rate(5m)` cycle), so this metric is the ONLY alarm-able signal for the `UnprocessedRecords` case — it does NOT trip the Lambda `Errors` alarm. A persistent breach = records repeatedly failing to meter (throttling, timestamp bounds, downstream issue) → investigate. - **`UsageRecordRejected`** (`*-usage-rejected`) — client-side guardrail rejections before metering (summed across reasons; per-reason breakdown on the dashboard); fix source rows + resubmit. **`BatchMeterUsageException`** (`*-batchmeterusage-exception`) — a REQUEST-level exception failed a whole call (dimension/license/etc.); pipeline bisects to isolate. **`CustomerNotSubscribed`** (`*-customer-not-subscribed`) — per-record status, no active subscription (do NOT retry). - Plus age-out alarms (`UsageAggregationExpired`/`UsageSubmissionExpired`, `>24h`) catch usage that silently never metered, and Lambda `Errors`/`Throttles`/DLQ-depth alarms catch pipeline failures. `DuplicateRecord` is a dashboard metric (informational — first submission already billed), not an alarm. --- ## QUERY PATH — Find, Debug, and Analyze Metering Records Full routing/patterns: `references/query-path.md` + `references/query-patterns.md`. **Capability boundary (state it; don't return a bounded answer as authoritative).** This query **USES** CloudTrail Event History (`LookupEvents`) in the seller's region, last ≤90 days, **page-bounded and processed in memory** — a recent, regional, SUBMISSIONS view (includes rejected/duplicate records that were NOT billed) for BASIC operational/debug queries (lookups + simple filters/counts/summaries by customer, dimension, status, time). It **RECOMMENDS** (does not run): Seller Reports/SDDS for billed totals + >90-day history; the host agent + model for complex/open-ended analytics (hand it the fetched data); and — for CA/LicenseArn metering with no LicenseArn→productCode mapping (single-product-stack context, CloudTrail `additionalEventData`, or the subscribers table) — only non-product-scoped queries (never guess attribution). Every result carries `complete`/`truncated`/`windowClipped`. **Before presenting a result, CONFIRM these signals:** if `complete` is false (page-truncated OR clipped at the 90-day retention limit), either re-run for a complete answer where feasible (narrow/adjust range for a clip; raise `--max-pages` or add filters for truncation) or state explicitly that the result is PARTIAL — what was clipped/truncated and the covered range — and point to Seller Reports for the authoritative/older portion. A truncated or clipped aggregate (summary/count/top_customers) is a **lower-bound sample, NOT authoritative**. Never report a partial result as the full requested range. Do not refuse a basic query just because a richer answer is possible in the host agent. **CloudTrail-derived SQL is the WRONG source for billing/usage analytics** — CloudTrail Lake OR Athena over a `trail → S3` export both see SUBMISSIONS only (rejected/duplicate, regional, no CA `productCode`); do NOT set up CloudTrail **Lake** for metering; for complex analytics / billing-grade totals / >90-day data use **SDDS** (recommend, don't run), and use a `trail → S3` (never Lake) only for long-term raw-submission audit retention. Full boundary: `references/query-path.md`. **Complex / billing-grade query steering — MUST NOT vs allowed sources (enforce; do not violate).** For any complex-analytics or billing-accuracy question over metering data: - **MUST NOT** recommend **CloudTrail Lake** (`create-event-data-store`) for metering — ever. - **MUST NOT** present CloudTrail (Event History OR a `trail → S3`/Athena export) as a source of **billed/billing-grade totals** — CloudTrail sees SUBMISSIONS only (includes rejected/duplicate, regional, no CA `productCode`), so it is never authoritative for revenue. - **Allowed sources only:** for billed/disbursed totals and >90-day billed history → **Seller Reports / AMMP Billed Revenue dashboard** and **SDDS** (recommend, do not run); for recent (≤90-day) regional SUBMISSION debugging → **CloudTrail Event History**; for complex/open-ended analytics → hand the fetched data to the **host agent + model**; for long-term RAW-submission audit retention only → a plain **`trail → S3`** (NOT Lake) + Athena, understanding it is submissions-not-billing. Route every complex-billing ask to these allowed sources and name why CloudTrail is not billing-authoritative. ### Steps 1. **Ask the metering region** (MUST — CloudTrail is regional). 2. Extract filters: `customer_id`, `status`, `dimension`, `start_date`/`end_date`, `query_type` (summary/detail/count/list_failures/top_customers), `top_n`. 3. Run the script (default: last 7 days): ```bash python3 ./scripts/query_metering.py \ --region \ [--days N] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] \ [--customer-id ACCT_ID] [--status STATUS] [--dimension DIM] \ [--product-code PC] [--deployment-product-code PC] \ [--query-type summary|detail|count|list_failures|top_customers] \ [--top-n N] [--limit N] [--max-pages N] ``` **CloudTrail Event History recipe (what the script does; use directly if querying by hand).** Event History is on by DEFAULT — no data store, no setup, **never CloudTrail Lake / `create-event-data-store`** for metering. Query IN the seller's metering region and filter on the metering event source: ```bash aws cloudtrail lookup-events --region \ --lookup-attributes AttributeKey=EventSource,AttributeValue=metering-marketplace.amazonaws.com \ --start-time --end-time ``` Each `BatchMeterUsage` event's CloudTrail `responseElements` carries **`results`** (per-record `status`: `Success`/`CustomerNotSubscribed`/`DuplicateRecord` — those are the ONLY per-record statuses) and **`unprocessedRecords`** — to verify a submission, check `results` vs `unprocessedRecords` FIRST (records in `unprocessedRecords` were not processed — see the `UnprocessedRecords` note below). CloudTrail lowercases the first letter of response fields, so read `results`/`status`/`meteringRecordId`/`unprocessedRecords` (lowercase) — the direct SDK `BatchMeterUsage` response uses PascalCase (`Results`/`Status`/ `MeteringRecordId`/`UnprocessedRecords`). An undefined dimension is NOT a per-record status — it fails the whole call with a request-level `InvalidUsageDimensionException` (see below). ≤90 days only; for older/billed totals use Seller Reports/SDDS (recommended, not queried). **CloudTrail is NOT revenue** — it shows submissions (incl. rejected/duplicate, not billed). Metered usage **bills at the START of the following month (the 2nd/3rd)** — e.g. November usage lands on the December invoice — and dashboard revenue is **estimated** until the month closes; use Seller Reports for billed/disbursed amounts. ### Status meanings Per-record `Results[].Status` values: | Status | Meaning | Action | |--------|---------|--------| | `Success` | Accepted and billed | None | | `CustomerNotSubscribed` | No active subscription | ⚠️ Do NOT retry | | `DuplicateRecord` | First-write-wins and reported; a differing-quantity resubmit is NOT billed | Safe only for an identical retry; never to change a quantity (under-billing risk) | Request-level exceptions (fail the ENTIRE `BatchMeterUsage` call, NOT a per-record status). Each has a **client-side guardrail reason code** the pipeline stamps when it rejects the row BEFORE the API call (`RejectedClientSide`, not billed), plus the **server-side exception** if a row reaches the API — surface BOTH when explaining a rejection: | Server-side exception | Client-side reason code | Meaning | Action | |-----------|-----------|---------|--------| | `InvalidUsageDimensionException` | `InvalidDimension` | A dimension not defined in the catalog (server-authoritative; case-sensitive; not billed) | Fix the dimension key / define it in AMMP. The pipeline isolates the offending record by bisection (depth-bounded, ⌈log2(batch size)⌉=5) so its co-batched records still meter, marks it `RejectedClientSide` (reason = the exception name), and emits the `BatchMeterUsageException` metric. | | `TimestampOutOfBoundsException` | `MalformedTimestamp` | A record older than 24h (e.g. a 30h-old row) or otherwise outside the window — REJECTED, not submitted | Fix the timestamp; the client-side guardrail rejects the row with reason `MalformedTimestamp` before batching, and one bad timestamp that reaches the API rejects the whole batch until isolated. | | `InvalidLicenseException` | `InvalidLicenseArn` | A malformed/invalid `LicenseArn` | Shape-validate client-side (reason `InvalidLicenseArn`); a server-side `InvalidLicenseException` is isolated by (bounded) bisection and marked `RejectedClientSide` with the exception name. | | `TooManyTagsException` | `TooManyTags` | More than 5 `usageAllocations` tags on a UsageRecord | Reduce to ≤5 tags; the client-side guardrail rejects the row with reason `TooManyTags` before batching. | **Sort-key / reject-code ordering:** the pipeline validates a row's shape BEFORE it can enter a batch. A row whose sort key (`customerAWSAccountId#dimension#timestamp`) carries a malformed or out-of-window timestamp is **rejected client-side with reason code `MalformedTimestamp`** (marked `RejectedClientSide`, emits `UsageRecordRejected`) — it never reaches `BatchMeterUsage`, so it does NOT surface as a server-side `TimestampOutOfBoundsException` unless a bad timestamp slips through into a batch. Always name the client-side `MalformedTimestamp` reason code for a malformed-timestamp sort key, and its server-side `TimestampOutOfBoundsException` equivalent. **Full reject-/status-code catalog (the ONE place to cite for any reason-code question).** A question like "what does `UnknownDimension` mean?" should be answered from this complete set, mapping the client-side guardrail reason code to its server-side equivalent: | Client-side reason code (`RejectedClientSide`, pre-API, not billed) | Server-side equivalent | Meaning | |---|---|---| | `MalformedSortKey` / `SortKeyMismatch` | — (never reaches API) | Sort key not `customerAWSAccountId#dimension#timestamp`, or its segments don't match the row's own attributes | | `MalformedTimestamp` / `TimestampOutOfWindow` | `TimestampOutOfBoundsException` | Non-whole-second, unparseable, or >24h-old timestamp | | `MissingDimension` | — | Row has no `dimension` | | `InvalidDimension` / `UnknownDimension` | `InvalidUsageDimensionException` | Dimension not defined in the catalog (case-sensitive) — `UnknownDimension`/`InvalidDimension` are the same "dimension not in the AMMP catalog" condition | | `NegativeQuantity` | — | Quantity < 0 | | `NonIntegerQuantity` | — | Quantity not a whole integer | | `TooManyTags` | `TooManyTagsException` | >5 `usageAllocations` tags on a record | | `TooManyAllocations` | — | >2500 merged tag-sets in a group | | `AllocationSumMismatch` | — | `AllocatedUsageQuantity` values don't sum to the row `quantity` | | `MixedAllocatedAndUnallocated` | — | Group mixes tagged and untagged non-zero rows | | `InvalidLicenseArn` | `InvalidLicenseException` | Malformed/invalid `LicenseArn` (also fires when products are mixed in one batch) | Plus the terminal per-record `Results[].Status` verdicts returned BY the API (not client-side reasons): **`Success`** (billed), **`DuplicateRecord`** (first-write-wins; a differing-quantity resubmit is NOT billed — under-billing risk, not "benign"), **`CustomerNotSubscribed`** (no active subscription — do NOT retry). And `UnprocessedRecords` (transient, retryable) — see below. **`UnprocessedRecords` (a THIRD, distinct outcome — neither a per-record `Results[].Status` verdict nor a request-level exception):** a PARTIAL-BATCH result (succeeded records in `results`; failed-to-process ones in `unprocessedRecords` — NOT billed, typically TRANSIENT `ThrottlingException`/`InternalServiceException`), SAFE to re-submit (idempotent); the submitter retries ONCE then leaves it for the NEXT scheduled run (alarmed via `UsageRecordUnprocessed`). Do NOT treat it as accepted/billed or confuse it with the FINAL `Results[].Status` verdicts above. **Data tiers:** CloudTrail Event History (≤90 days, free, real-time) is the tier the skill queries directly; it shows ALL submissions (incl. rejected/duplicate), Seller Reports show only billed — so "totals don't match" = the rejected/duplicate delta. Two separate history questions, don't conflate them: > **Reconciling SUBMITTED (CloudTrail) vs BILLED (Seller Reports).** Treat **Seller Reports / AMMP Billed Revenue as the billed source of truth**; CloudTrail is submissions only. To reconcile, **filter CloudTrail to `Status=Success`** (exclude `DuplicateRecord`, `CustomerNotSubscribed`, and request-level exceptions — none of those bill) and compare that to the billed report; the leftover gap is the expected rejected/duplicate delta. **Watch for `DuplicateRecord`s with DIFFERENT quantities** for the same `(account, licenseArn, dimension, hour)` — that is NOT benign: first-write-wins means the later (often larger) quantity was NOT billed, so it can indicate **under-reporting/under-billing**. Surface those as a reconciliation red flag rather than dismissing duplicates. - **BILLED history (any range) needs NO setup** — the AMMP Insights **"Billed Revenue" dashboard** (only `aws-marketplace:GetSellerDashboard`; default 6 months, widen the invoice-date filter). Console-only (QuickSight) + manual CSV export — **no on-demand billed API**. Programmatic billed data = **SDDS** (daily S3 push + your Athena/ETL), but push-only and **enrollment-forward (no backfill)**. Skill recommends, doesn't run; **never `GenerateDataSet`**. Detail: `references/seller-reports.md`. - **Discounts / private offers are NOT a metering or Seller-Reports concern — redirect to the public AWS Marketplace channel (AMMP).** If a seller asks why billed amounts differ from metered usage because of a **discount or private offer**, or how to apply/change one, do NOT try to explain or reconcile it from metering data and do NOT stop at "out of metering scope." The pricing that turns metered quantity into billed revenue (public price, private offers, discounts, EULA terms) is managed in the **AWS Marketplace Management Portal (AMMP)** — state that the discount/private-offer delta is expected (Seller Reports show BILLED revenue after any negotiated discount, while CloudTrail shows raw metered SUBMISSIONS) and redirect discount/private-offer creation and management to AMMP → [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/) / [private offers](https://docs.aws.amazon.com/marketplace/latest/userguide/private-offers-overview.html). - **RAW SUBMISSION history beyond 90 days has NO out-of-the-box source** (Seller Reports/SDDS are billed-only; Event History keeps 90 days). Retain via a self-managed **CloudTrail trail → S3** on `metering-marketplace.amazonaws.com` (plain trail, **NOT Lake**; Athena) — also **from setup forward, no backfill**; complementary DynamoDB PITR export of `aggregated_usage`. Detail: `references/query-patterns.md`. ### Query references - Routing + parameters: `references/query-path.md` · CloudTrail CLI patterns + pagination: `references/query-patterns.md` - Seller Reports reconciliation + SDDS automation boundary: `references/seller-reports.md` · Dimension reference: `references/dimension-reference.md` --- ## Key APIs | API | Region | Purpose | |-----|--------|---------| | ResolveCustomer | any region (seller's choice) | Resolve token → LicenseArn + customerAWSAccountId + productCode at registration; regional, from the publishing account; independent of the BatchMeterUsage region | | BatchMeterUsage | seller's metering region | Submit usage records (hourly) | | DescribeEntity | us-east-1 | Validate product / type / visibility | | LookupEvents | seller's region | Query metering records (≤90 days) | IAM action names: `aws-marketplace:BatchMeterUsage` (meter), `aws-marketplace:ResolveCustomer` (register), `aws-marketplace:GetSellerDashboard` (reports). Namespace is `aws-marketplace:`, NOT `meteringmarketplace:*`. When diagnosing AccessDenied, name the exact action and check the execution role, condition keys, and Resource-ARN mismatches. ## Security - **Least privilege:** execution roles grant ONLY the actions used — meter path: `aws-marketplace:BatchMeterUsage` + scoped DynamoDB `Query`/`UpdateItem` on its tables + the `metering_pending` index; register: `aws-marketplace:ResolveCustomer` + scoped `Query` on the `customerAWSAccountId` GSI + item ops. **No `dynamodb:Scan`** (lookups use GSI `Query`); never `dynamodb:*` or broad `aws-marketplace:*`. - **No swallowed auth errors:** subscriber/license lookups do NOT catch `AccessDeniedException` as "not found" — permission/config errors surface (Lambda error / 500 / DLQ). - **Encryption at rest:** SQS (`SqsManagedSseEnabled`), SNS (`alias/aws/sns`), DynamoDB (`SSEEnabled`); Lambda + API log groups are explicit resources with `RetentionInDays` + optional `KmsKeyId` (they contain buyer account IDs / license ARNs). - **Public registration API:** intentionally open (Marketplace POSTs the token unauthenticated) → template attaches a baseline WAF WebACL by default (rate-based + common-exploit; `WebAclArn` overrides); API Gateway throttling + access logging always on; register Lambda returns security headers and persists ONLY an allowlist of length-bounded fields (`AllowedRegistrationFields`). - **Credentials (ephemeral-first):** SSO → `sts assume-role`; no long-lived keys, don't ask for keys first. Deployer role uses a conditioned trust policy (not open `:root`) + permissions-boundary-bounded `iam:CreateRole`. - **Stage name:** `StageName` has no default + an `AllowedPattern` rejecting empty; mandatory questionnaire answer; `sam deploy` and `deploy.sh` fail fast (no `prod` fallback). - **Event scoping:** EventBridge rule scoped to `source: ["aws.agreement-marketplace"]`; the EventBridge→SQS policy via `aws:SourceArn`. - **Data classification:** customer AWS account IDs + agreement metadata are sensitive — avoid logging full identifiers; encrypt log groups that contain them.