Setup Path

IMPORTANT: Before proceeding, verify the product is SaaS with usage-based pricing (ExternallyMetered dimensions). Query the Catalog API after getting credentials. If the product is AMI, Container, or SaaS Contract-only, respond that the product type is out of scope and redirect to the public AWS documentation (opens in a new tab).

Seller Questionnaire

Ask ALL five questions before generating any code:

Q1: Product code and dimensions?

• “What is your Marketplace product code (or entity ID) and which usage dimensions do you want to meter?”
• They MUST provide the product code (like 4ml54db8vrmjuykaw1psroool) and at least one dimension key.

Q2: Are you the ISV/seller or building for one?

• Confirms they have access to the seller account and AWS Marketplace Management Portal.

Q3: Multi-region or single region?

• Events stack is always in us-east-1 (marketplace lifecycle events emit only there). Deploy a metering (main) stack in each region where the seller runs and meters their SaaS, each with its own regional usage table.
• BatchMeterUsage is a regional API — call it in-region from where the usage occurred (for SaaS on another cloud or on-premise, use the nearest AWS region). There is no benefit to routing all usage through one region, and doing so works against data-residency (e.g. EU usage should stay in eu-west-1).
• Metering records are per-region. De-duplication is per CustomerAWSAccountId + LicenseArn + dimension + hour (SaaS CA products), scoped to the region the record was submitted in, first-write-wins within that region. A buyer whose usage genuinely spans regions is metered in each region where the usage actually occurred — the same customer/dimension/hour submitted in different regions is expected and correct. Do NOT force all of a customer’s usage into a single region and do NOT funnel every customer’s usage into one global table.
• Supported regions: see BatchMeterUsage region support (opens in a new tab).

Q4: API stage name (mandatory)?

• “What API Gateway stage name should the registration endpoint use — for example v1, live, or prod? This is your choice and there is no default.”
• The StageName template parameter has no default and an AllowedPattern that rejects an empty value. The seller MUST supply a non-empty value; there is no silent default and no fallback to prod. A direct sam deploy fails fast at the template level if it is missing/empty, and deploy.sh performs the same check (pass the seller’s choice via STAGE_NAME; the fulfillment URL tracks it).

Q5: Does a metering stack already exist for this product?

• If yes (or the skill otherwise determines one exists), treat this as a modify/extend case: gather context on the seller’s existing stack and inspect it before changing anything. Do NOT assume it follows this skill’s awsmp-* naming — see references/existing-sellers.md.

CCP is out of scope (handled at the Product Type Gate above). If the product is Contract with Consumption Pricing, contract-only, AMI, or Container, respond that it is out of scope and redirect to the public AWS documentation (opens in a new tab); do NOT provide CCP implementation steps, code, or API sequences.

Concurrent Agreements is the default. All new products use CustomerAWSAccountId + LicenseArn. Do not ask the seller — this is the default for all new products.

Product Portfolio: Stack Naming Convention

Supported Features

Prerequisites

• AWS account with Marketplace seller registration
• Product listed in AWS Marketplace (product code assigned)
• At least one usage dimension configured on the product
• Product must be SaaS with ExternallyMetered dimensions (verified via Catalog API)

AWS Credentials (ephemeral-first — configure before deploying)

Have the seller configure ephemeral credentials in their own environment before you deploy or run tests — do NOT ask them to hand over long-lived IAM user access keys, and do NOT ask for credentials outright as a first step. Preferred order:

1. IAM Identity Center / SSO — aws configure sso && aws sso login
2. STS assume-role — assume a dedicated deployer role (session includes AWS_SESSION_TOKEN)
3. Last resort: short-lived STS session env vars (with AWS_SESSION_TOKEN) — never long-lived user keys

Then verify with aws sts get-caller-identity and confirm the correct seller account before proceeding. The same ephemeral credentials are used for Catalog API validation, deployment, and integration testing.

For the ephemeral-first setup commands and the full least-privilege IAM deployer policy (conditioned trust policy + permissions-boundary’d iam:CreateRole), load references/iam-credentials.md.

Validate Product Code and Dimensions via Catalog API

After credentials are verified, run this command. Do NOT skip — incorrect values cause runtime failures.

Important: The product ID (prod-xxx) is NOT the product code. Always verify via the Catalog API or AMMP.

Tool Requirements

• A recent AWS SAM CLI (sam --version) and AWS CLI v2 (aws --version). Verify the installed versions work; consult the SAM CLI / AWS CLI release notes if a command is unsupported.

Deployment Steps

For the full 6-step deployment walkthrough, load references/deployment-steps.md.

Summary:

1. Generate SAM template + Lambda code
2. Deploy Events Stack (us-east-1) — shared EventBridge rules
3. Deploy Main Stack (seller’s region) — Lambda + DynamoDB + API Gateway
4. Configure Fulfillment URL in AMMP
5. Test End-to-End (subscribe → resolve → write conforming usage row → discoverer → aggregator → submitter → verify Aggregated + Success)
6. Validate via CloudTrail logs

⚠️ Usage Ingestion — Seller’s Responsibility

The deployed stacks provide the metering pipeline (discoverer → aggregator → cleanup → submitter; a shared subscription path) that reads usage rows from the usage DynamoDB table and submits them to BatchMeterUsage. However, writing usage rows into the table is entirely the seller’s responsibility.

The seller must build:

• Usage capture — instrument their application to record per-customer, per-dimension usage events
• Cross-account aggregation (if multi-account runtime) — collect usage from all runtime accounts into the central metering account
• Write pipeline — durably write usage rows into the usage DynamoDB table, in the exact schema below, before the hour is aggregated

The pipeline meters whatever conforms to the schema; it does not distinguish billable from non-billable usage and applies no business filtering. The seller must ensure only metered-eligible usage lands in the table.

Recommended pattern: Durable buffer (SQS/Kinesis) → per-second/hour idempotent aggregator (Lambda/Step Functions) → usage DynamoDB table.

Usage-row writer contract (what every row MUST look like)

The pipeline reads rows on trust for what it cannot re-derive, and reason-code-rejects (raw-row meteringStatus = RejectedClientSide, UsageRecordRejected metric) what it can check. A row MUST have:

The meteringPending accuracy point is the one the pipeline cannot self-correct. If the writer stamps a bucket that disagrees with the row’s timestamp hour, the row is discovered under a bucket whose read-prefix its sort key does not match, so its quantity is silently omitted and its marker is never cleared. There is no client-side reject for it (the row is effectively invisible to the group that would validate it). Getting meteringPending == floor(timestamp, hour) right is a hard writer obligation — the hands-on test below is how the seller confirms it.

What the seller owns once the stacks are in place

After the two stacks deploy successfully, the skill SHALL make these ongoing seller responsibilities explicit:

1. Write usage rows conforming to the contract above (the only thing that makes metering happen).
2. Wire the alarms — subscribe an SNS topic / notification to the created alarms (AlertsTopicArn); the stack raises them but acting on them is the seller’s job (deployment-steps.md).
3. Watch the health dashboards — especially UsageRecordRejected (writer-contract violations, sliced by Reason), BatchMeterUsageException / CustomerNotSubscribed (terminal, server-side), and UsageAggregationExpired (raw usage aged out before aggregation) / UsageSubmissionExpired (aggregated but not submitted in time).
4. Manage dimensions in the catalog — add/rename pricing dimensions in AMMP; no redeploy is needed (dimension validity is server-authoritative).
5. Set the Fulfillment URL in AMMP to the branded registration page URL (the CloudFront/custom-domain front-end that captures buyer/KYB fields and calls RegistrationUrl); the raw RegistrationUrl is only a bare-bones smoke-test fallback. See references/registration-page.md. (A one-time manual seller step.)
6. Own the deployed source — the generated template + handlers live in the seller’s workspace; re-deploy from there and customize the marked TODO: sections.

The skill SHALL then walk the seller through the hands-on end-to-end test in references/deployment-steps.md Step 5 — subscribe → verify registration/EventBridge → write a conforming test usage row (correct second-precision sort key + matching meteringPending) → trigger discoverer/aggregator/submitter → verify the raw row finalizes as Aggregated and the aggregated record reaches Success. This exercise is how each writer-contract expectation above is demonstrated and confirmed to be met, and how a mis-stamped meteringPending (otherwise silent) is surfaced.

Additional References

• Concurrent Agreements details: Load references/concurrent-agreements.md
• Architecture diagram + data model: Load references/architecture.md
• Troubleshooting errors: Load references/troubleshooting.md
• Existing sellers (modify/extend): Load references/existing-sellers.md

Common Mistakes

1. Using CustomerIdentifier instead of CustomerAWSAccountId in UsageRecords
2. Mixing ProductCode and LicenseArn for the same customer/hour
3. Using SNS instead of EventBridge (SNS lacks CustomerAWSAccountId)
4. Deploying EventBridge rule in seller’s region instead of us-east-1
5. Dimension key not defined in the catalog — BatchMeterUsage fails the call with a request-level InvalidUsageDimensionException (server-authoritative; the submitter isolates the record → RejectedClientSide reason InvalidUsageDimensionException; surfaced on the BatchMeterUsageException metric/alarm, not billed). Fix the key or add the dimension in AMMP; no redeploy needed.
6. Writing the sort-key timestamp at millisecond precision (.000Z) instead of whole-second YYYY-MM-DDTHH:MM:SS — rejected as MalformedTimestamp.
7. Stamping meteringPending with an hour that doesn’t match the row’s timestamp hour — the row is discovered under the wrong bucket and silently never metered (the one failure the pipeline can’t catch; verify via the Step 5 test).
8. Activating metering on Purchase Agreement Created — that event carries no licenseArn and is not consumed by the metering path. Metering follows License Updated (access granted) and the usage table’s metering_pending GSI.

Security

• Lambda needs ONLY aws-marketplace:BatchMeterUsage + DynamoDB read/write
• EventBridge rule scoped to source: ["aws.agreement-marketplace"]
• Enable CloudTrail for audit
• Separate accounts for prod vs test

Unified Subscribers Table (exact schema)

Use ONE unified DynamoDB table for SUBSCRIPTION/AGREEMENT STATE (do NOT split subscription state across separate “customer-profiles” + “subscriptions” tables). Buyer PII / registration-form data is a SEPARATE concern and lives in its own per-Region customer-profile table (below) — that separation is intentional (keeps the subscribers table PII-free), not the old split-subscription-state anti-pattern.

• Concurrent Agreements (default): licenseArn = PARTITION key (HASH), customerAWSAccountId = SORT key (RANGE). LicenseArn MUST be the partition key. One buyer with N concurrent agreements = N rows (same customerAWSAccountId, different licenseArn), tracked independently.
• Legacy (pre-CA): customerAWSAccountId = partition key (understand the seller’s actual schema first; do not impose the CA layout).
• Attributes on a new CA record (PII-FREE): productCode, agreementId, agreementStatus (active/inactive — agreement lifecycle), subscriptionStatus (active/deprovisioning/inactive — license lifecycle; no deprovisioned value), registeredRegions (DynamoDB String Set of AWS Region names, added idempotently via ADD, reference-only). It does NOT carry customerIdentifier (deprecated, legacy-only) and does NOT carry buyer PII / registration-form data. Buyer PII lives in the per-Region customer-profile table (awsmp-<productCode>-customer-profile, PK licenseArn + SK customerAWSAccountId, seller-requested GSIs), written in-region by the register Lambda — so the subscribers table stays PII-free and safe in us-east-1 for opt-in-Region products.
• Two GSIs so lookups never need a Scan: customerAWSAccountId-index (register lookup / all agreements for one buyer) and agreementId-index (subscription lookup when an event omits license.arn).

Usage table: keyed by licenseArn (PARTITION key) + customerAWSAccountId#dimension#timestamp (SORT key) — the sort-key value is the #-delimited composite {customerAWSAccountId}#{dimension}#{timestamp} at second precision (YYYY-MM-DDTHH:MM:SS), bounding a group at ≤3600 rows/hour. Each item ALSO stores customerAWSAccountId, dimension, and timestamp as top-level attributes so the pipeline reads them without parsing the sort key. It has a sparse metering_pending GSI (HASH = meteringPending hour-bucket, RANGE = licenseArn): the usage writer sets meteringPending when it writes a row, and the pipeline clears it after the row’s aggregation group reaches a terminal result.

Metering pipeline flow (recite when asked how metering works)

Metering is a decoupled, SQS-connected pipeline driven by the usage table’s metering_pending GSI, NOT by registration state — not every seller uses ResolveCustomer (some obtain the LicenseArn via EventBridge or SDDS and never register), so metering must not depend on a registered subscriber. The stages:

1. Discoverer (hourly, metering_pending GSI): queries the GSI for a completed hour bucket and enqueues ONE work message per (licenseArn, customerAWSAccountId, dimension, hourBucket) group onto the work SQS queue. It only meters completed hours in the now-23h … now-1h window (never the in-progress hour) and only once an hour has been closed for MeteringLockHours (default 1). It does NOT read group rows, aggregate, submit, or write back. The same discoverer, on its age-out targets, terminally expires raw rows older than 24h that were never aggregated (REMOVE meteringPending, meteringStatus=AggregationExpired, UsageAggregationExpired metric).
2. Aggregator (SQS-triggered, one message = one group): reads the group’s rows via the targeted begins_with prefix (streamed fold), takes customerAWSAccountId/dimension from the rows (no subscriber lookup), aggregates all second-precision rows into ONE quantity, and MERGES seller-provided usageAllocations. It runs the structural/format client-side validations (dimension present; second-precision sort key with matching segments; non-negative integer quantity; timestamp window; identifier shape; allocation invariants) — dimension NAME validity is left to BatchMeterUsage. A valid group is written as ONE record via conditional PutItem into the awsmp-aggregated-usage table (idempotency commit point); a rejected group is finalized RejectedClientSide with a reason code + UsageRecordRejected metric.
3. Cleanup (SQS-triggered): after the aggregated record is durably written, clears meteringPending on the raw rows and stamps meteringStatus=Aggregated. The raw usage table NEVER carries the submission outcome — its meteringStatus domain is exactly Aggregated / RejectedClientSide / AggregationExpired.
4. Submitter (EventBridge rate(5 minutes), reserved=1): reads pending records from awsmp-aggregated-usage over the now-23h … now-1h window OLDEST-first, coalesces ≤25 UsageRecords per BatchMeterUsage call, retries UnprocessedRecords once, and writes the returned MeteringRecordId + per-record Status (Success/DuplicateRecord/CustomerNotSubscribed/…) back onto the awsmp-aggregated-usage record only (REMOVE its meteringPending). Records still unprocessed after the retry keep their marker and the invocation FAILS so the Errors alarm fires. It finalizes deprovisioning subscribers after a successful final flush.
5. Expiry (separate EventBridge rate(5 minutes) target, reserved=1): terminally expires a pending awsmp-aggregated-usage record that can no longer be metered — its hour is >24h in the past, OR it is a previous-month record and the month-end grace has closed (on/after 06:00 UTC on the 1st) — REMOVE meteringPending, meteringStatus=SubmissionExpired, UsageSubmissionExpired metric.

Zero-quantity groups: while its hour is still inside the window, a group summing to 0 is left pending (not submitted) so the seller can still write usage for that hour — submitting a 0 early would lock the hour at 0 via first-write-wins dedup. At the oldest edge of the window it IS submitted as Quantity: 0 to close the hour out.

Throughput / concurrency: the pipeline uses FIXED concurrency (there is no single meter Lambda and no MeterReservedConcurrency parameter): discoverer ReservedConcurrentExecutions=30, aggregator SQS-ESM MaximumConcurrency: 50 with ReportBatchItemFailures, cleanup SQS-ESM MaximumConcurrency (bounded per-partition writer), submitter and expiry reserved=1. SQS absorbs bursts, so scale comes from queue depth draining rather than raising Lambda concurrency. If a seller needs higher sustained metering TPS than the reserved=1 serial submitter + BatchMeterUsage rate limit allow, advise them to contact AWS Marketplace Seller Operations rather than raising these values unsafely.

Deployment modes — the aggregation pipeline is OPTIONAL

The full pipeline above (discoverer → aggregator → cleanup → submitter → submission-expiry) is the default and is for sellers who write RAW per-second usage rows. A seller who already produces finalized hourly aggregated records upstream can instead choose direct-submit mode (DEPLOYMENT_MODE=direct-submit): the skill deploys ONLY the aggregated_usage table + submitter + submission-expiry + the register/subscription path — no raw usage table, no work/cleanup queues, and no discoverer/aggregator/cleanup. The seller writes finalized records straight into awsmp-aggregated-usage:

Finalize before insert (critical). ANY record present in aggregated_usage MAY be picked up and submitted on the next 5-minute submitter run. Write a record ONLY when it is FINAL for its (licenseArn, customerAWSAccountId, dimension, hour) — a second write for an already-submitted group returns DuplicateRecord (first-write-wins) and the later quantity is not billed (under-billing risk). The seller owns the upstream aggregation/idempotency in this mode; the skill provides no raw-row aggregation.

The alarms and health dashboard are created to match the deployed components — direct-submit mode omits the aggregation-stage alarms/widgets (aggregator/cleanup/discoverer, work/cleanup DLQ, UsageAggregationExpired, UsageRecordRejected) and shows a submitter/expiry-focused dashboard.

Mode is not a one-way door. A seller can start in either mode and switch later (change DEPLOYMENT_MODE and re-deploy), and the skill can layer on additional implementation as needs evolve. Switching an actively-metering live stack is a stack UPDATE that adds/removes the mode-specific resources: the raw usage table is Retain (its data survives), but moving to direct-submit REMOVES the work/cleanup queues + discoverer/aggregator/cleanup — confirm the blast radius with the seller before flipping the mode on a live stack.

Vendor Metered Tagging (VMT)

VMT lets sellers break usage down by seller-defined tags. The allocation breakdown is the seller’s responsibility, provided on each usage row — there is NO enable flag. A usage row participates in VMT simply by carrying a usageAllocations attribute (a list of {AllocatedUsageQuantity, Tags:[{Key,Value}]} objects in the exact BatchMeterUsage UsageAllocation shape). The aggregator MERGES the per-row allocations of a group into the hour’s single UsageRecord (summing identical tag sets); it never decides or derives the tag split.

Rules the usage-writer must follow (the skill explains these at initial integration):

• Each row’s AllocatedUsageQuantity values SHALL sum to that row’s own quantity.
• Max 5 tags per allocation; max 2500 merged allocations per UsageRecord (a group with more distinct tag sets is rejected as TooManyAllocations).
• All-or-nothing per group: for a given (licenseArn, customerAWSAccountId, dimension, hour), either every non-zero row carries usageAllocations or none does. Mixing tagged and untagged non-zero rows is rejected client-side (MixedAllocatedAndUnallocated). Zero-quantity rows are ignored for this check. Different groups in the same hour/batch may independently have or omit allocations.
• The merged allocation sum must equal the record Quantity (else AllocationSumMismatch) — this is automatic if each row’s allocations sum to its quantity.
• If a group has no tagged rows, UsageAllocations is omitted.

Ask the seller for their real tag keys/values — the packaged code carries no illustrative tag and no VmtEnabled/VmtTagAttribute parameter.

Usage-writer quantity contract

Usage quantities MUST be non-negative integers. The aggregator rejects a negative (NegativeQuantity), fractional/decimal (NonIntegerQuantity), or non-numeric (NonNumericQuantity) quantity client-side — it never truncates (e.g. 2.5→2) or clamps a negative to 0. Aggregate/round in your writer before persisting. A 0 quantity is valid (not a rejection).

ResolveCustomer token behavior

• Registration tokens are short-lived (~4 hours) and reusable until they expire (NOT one-time-use — re-resolving the same token before expiry returns the same result).
• ExpiredTokenException → the buyer re-does “Set up your account” in Marketplace for a fresh token (a full resubscribe is NOT required).
• After a successful resolve, persist CustomerAWSAccountId + LicenseArn + ProductCode and append the invocation Region to registeredRegions (idempotent). Do NOT persist CustomerIdentifier for a new integration (deprecated, legacy-only).

TimestampOutOfBounds

• BatchMeterUsage accepts timestamps within the last 24 hours; older records → TimestampOutOfBoundsException, and one bad timestamp rejects the ENTIRE batch.
• The pipeline’s hourly now-23h … now-1h catch-up window recovers a missed/failed run within 24 hours (the discoverer re-enqueues pending hours; the submitter re-drains aggregated_usage). A 6-hour month-boundary grace period applies (previous-month records accepted until 06:00 UTC on the 1st).

Cancellation event model

• License Updated → agreementStatus = active and subscriptionStatus = active.
• License Deprovisioned → subscriptionStatus = deprovisioning (+ a deprovisioningExpiry); OPENS the ~1-hour flush window; the pipeline flushes any remaining aggregated usage, and the events-stack deprovision-cleanup Lambda (rate(15m)) sets subscriptionStatus = inactive once deprovisioningExpiry passes (time-based, not the submitter).
• Purchase Agreement Ended → agreementStatus = inactive ONLY (does NOT stop metering or flush).
• Purchase Agreement Amended → update agreement metadata (stays active).
• Purchase Agreement Created → not consumed by metering; the seller handles it where needed.