Architecture

Data Model

Unified Subscribers Table — a SINGLE table holding subscription/agreement STATE, PII-FREE. Lives in us-east-1 alongside EventBridge. Populated by EventBridge events and updated by the register Lambda (identity + statuses + registeredRegions only). Buyer registration-form data (PII) is NOT stored here — it lives in the per-Region customer-profile table (below).

For Concurrent Agreements (default, new products): licenseArn is the PARTITION key, customerAWSAccountId is the sort key. A buyer with multiple concurrent agreements has multiple rows (same customerAWSAccountId, different licenseArn), tracked independently.

For legacy (pre-CA) products: key by customerAWSAccountId alone.

The subscribers table is PII-FREE. It carries only the CA identity (licenseArn, customerAWSAccountId, productCode, agreementId), the two lifecycle statuses, and registeredRegions. Buyer registration-form data (PII — contact name, email, company, KYB, seller-defined fields) is NOT stored here; it lives in the per-Region customer-profile table (below), written in-region by the register Lambda. Because it holds no PII, the subscribers table is safe in us-east-1 even when the product/buyers operate in other (opt-in) Regions.

Customer-profile table (per Region) — awsmp-<productCode>-customer-profile, keyed by licenseArn (PK) + customerAWSAccountId (SK), deployed IN EACH metering/registration Region. Holds the seller’s allowlisted registration/KYB fields (buyer PII), with additional seller-requested GSIs on those fields. Written by the in-region register Lambda; kept in-region so buyer PII is never replicated to us-east-1. Not on the metering path.

Mapping a licenseArn to the seller’s internal SaaS tenant ID is the SELLER’s responsibility — this skill does not own the tenant model. AWS Marketplace identifies a buyer by licenseArn (+ customerAWSAccountId); how that maps to the seller’s own tenant/account/org ID is the seller’s application concern. The skill provides TWO places the seller can anchor that mapping, and the seller CHOOSES which (or both):

• Subscribers table (us-east-1) — carries the licenseArn from the License Updated EventBridge event (the authoritative, refreshed-on-renewal source; PII-free, so store only a non-PII internal tenant identifier here if you add one).
• Customer-profile table (in-Region) — carries the licenseArn captured at registration time (when the buyer clicks “Set up your account” and ResolveCustomer runs), alongside the buyer’s registration/KYB fields — a natural home if the tenant record is created from the registration form.

A row may exist in one before the other (registration and License Updated can arrive in either order), so a seller that needs the mapping available from the earliest moment often writes it in BOTH. The seller adds their own tenantId (or equivalent) attribute — the skill neither invents nor requires a specific tenant-ID scheme — and, if they need to look a tenant up by that ID, defines a GSI on it (on the customer-profile table for a PII/registration-derived ID, or on the subscribers table for a non-PII one).

Usage Table — keyed by licenseArn (PK) + customerAWSAccountId#dimension#timestamp (SK, second precision). Keying by licenseArn (not account) ensures usage is attributed per-agreement, preventing double-billing when a buyer holds multiple concurrent licenses. customerAWSAccountId, dimension, and timestamp are also stored as top-level attributes so the pipeline reads them without parsing the sort key. The seller writes usage here (and sets meteringPending); the metering pipeline reads it and calls BatchMeterUsage.

Event Flow (Order of Operations)

Status lifecycle: agreementStatus: active (License Updated) → inactive (Purchase Agreement Ended). subscriptionStatus: active (License Updated) → deprovisioning (License Deprovisioned opens the ~1-hour flush window) → inactive (deprovision-cleanup Lambda, once deprovisioningExpiry passes). The two move independently and are never conflated. Metering decisions follow subscriptionStatus / the metering_pending GSI, not agreementStatus or registeredRegions.

Purchase Agreement Created — seller use cases

The metering path does not consume Purchase Agreement Created, but it is a useful signal for other seller workflows. Per the AWS Marketplace SaaS EventBridge integration, this event fires when a new agreement is created, an existing agreement is replaced, or an existing agreement is renewed, and is delivered to both the manufacturer and proposer roles. Sellers commonly use it to:

• Post-sale onboarding / provisioning — kick off tenant provisioning, welcome emails, or CRM/opportunity updates as soon as a buyer subscribes (before the license arrives).
• Free-trial detection — call DescribeAgreement to determine whether the new agreement is a free trial and branch onboarding accordingly.
• Renewal / replacement tracking — because the event also fires on replace/renew, use agreement.id (and any prior-agreement linkage) to track renewals and upgrades.
• CPPO awareness — the manufacturer vs proposer variants differ by the presence of a resaleAuthorization ID; use this to distinguish direct vs channel-partner resale deals.

To act on it, add an EventBridge rule that matches detail-type: "Purchase Agreement Created - Manufacturer" (and/or - Proposer) with source: "aws.agreement-marketplace" and route it to your own target — do not add it to the metering Subscription Lambda. References:

• Managing SaaS subscription events with Amazon EventBridge (opens in a new tab)
• When a SaaS subscription ends / is cancelled (opens in a new tab)

Key insight: The subscribers table lives in us-east-1 alongside EventBridge. When the metering region is a different region, the register Lambda and the metering pipeline (discoverer/submitter) read it cross-region. If the seller’s metering region is also us-east-1, the events stack and main stack are both in us-east-1 and everything is single-region — no cross-region reads at all. us-east-1 is a fully supported metering region for BatchMeterUsage.

Multi-region sellers: Each metering region gets its own main stack (usage table + Lambdas). All regions share the single subscribers table in us-east-1. Deploy the events stack once (us-east-1), then deploy the main stack to each metering region — which MAY include us-east-1 itself.