Concurrent Agreements

What Changed

Correct BatchMeterUsage Payload

Incorrect Patterns (Common AI-Generated Mistakes)

ResolveCustomer Response — What to Store

ResolveCustomer returns LicenseArn, CustomerAWSAccountId, and ProductCode (plus a legacy, now-deprecated CustomerIdentifier that is null for new integrations). Store the first three, and use LicenseArn + CustomerAWSAccountId for metering:

Key Fact — ResolveCustomer returns LicenseArn directly: ResolveCustomer returns a top-level LicenseArn field along with CustomerAWSAccountId and ProductCode. For NEW (Concurrent Agreements) integrations, CustomerIdentifier is deprecated and null/absent — do NOT use it and do NOT treat its value as the LicenseArn. Persist LicenseArn + CustomerAWSAccountId from the ResolveCustomer response; both are also reaffirmed by the License Updated EventBridge event (a row can alternatively be created from that event when a seller never calls ResolveCustomer). Downstream (BatchMeterUsage, entitlement checks) require LicenseArn + CustomerAWSAccountId.

Key Fact: ResolveCustomer succeeding only means the registration token is valid — it does NOT confirm the subscription is active. Wait for the EventBridge License Updated / subscribe-succeed event before starting to meter.

Unified Subscribers Table (DynamoDB schema)

Store subscribers in a SINGLE unified table (not separate customer-profiles + subscriptions tables). The primary key depends on the integration pattern:

Unified table attributes (PII-FREE): licenseArn (PK), customerAWSAccountId (SK), productCode, agreementId, agreementStatus (active / inactive — agreement lifecycle), subscriptionStatus (active / deprovisioning / inactive — license lifecycle; there is no deprovisioned value), and registeredRegions (a DynamoDB String Set (SS) of AWS Region names where the buyer was registered, added idempotently via ADD — reference only, never gates metering). It does NOT carry customerIdentifier for a new CA integration (deprecated, legacy-only) and does NOT carry buyer PII / registration-form data — that lives in the per-Region customer-profile table (keyed licenseArn PK + customerAWSAccountId SK, seller GSIs), written in-region by the register Lambda. Keeping the subscribers table PII-free is why it can safely live in us-east-1 even for opt-in-Region products. The subscribers table defines 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).

Critical: For CA products, licenseArn MUST be the partition key — NOT customerAWSAccountId and NOT licenseArn as a sort key. A buyer with two concurrent agreements has two rows (same customerAWSAccountId, different licenseArn). Keying by account alone would collapse them and cause double-billing or lost usage. The usage table is likewise keyed by licenseArn (PK) + customerAWSAccountId#dimension#timestamp (SK) so usage is attributed per-agreement. This unified single-table design aligns with the AWS Marketplace Serverless SaaS Integration reference architecture. Metering is driven by the usage table’s metering_pending GSI (not by subscriber/registration state): the meter Lambda queries that GSI for licenseArns with pending usage, builds each UsageRecord entirely from the usage rows (which carry customerAWSAccountId), and only looks up the subscriber row to read/update subscriptionStatus. Usage rows are keyed by the real licenseArn — there are no pending:-prefixed placeholder rows.

The table lives in us-east-1 alongside the EventBridge events (that is the only region where marketplace lifecycle events are emitted).

Key Rules

1. New products: MUST use CustomerAWSAccountId + LicenseArn per UsageRecord. Do NOT include ProductCode at the request level.
2. Existing (legacy) products: Can continue using CustomerIdentifier + ProductCode, but should migrate to the new pattern.
3. Never mix: Do NOT send LicenseArn and ProductCode for the same customer in the same hour. This causes duplicate billing.
4. CustomerIdentifier is NOT for metering: It is an opaque identifier for customer lookup. Use CustomerAWSAccountId in UsageRecords.
5. LicenseArn is per-agreement: A single buyer can have multiple LicenseArn values for the same product. Each represents a separate agreement with separate usage tracking.

Metering Cadence & Deduplication

• Call frequency: Once per hour (use EventBridge rate(1 hour) schedule)
• Timestamp window: Each UsageRecord timestamp must be within the last 24 hours of the event. Anything 24 hours or older is rejected with TimestampOutOfBoundsException (and one bad timestamp rejects the whole batch). A 6-hour month-boundary grace period applies: previous-month records are accepted until 06:00 UTC on the 1st of the next month.
• DuplicateRecord = first-write-wins and REPORTED (NOT simply “benign”): If you resend a record for the same (CustomerAWSAccountId + LicenseArn + dimension + hour), the API returns that record with Status = DuplicateRecord (NOT Success, and present in the response — not silently absent). The FIRST submitted quantity stays final/billed; a resubmission with a DIFFERENT quantity is NOT billed. If a seller intended to correct 5→10, the correction is not applied and they UNDER-BILL by 5. Warn sellers: an unexpected DuplicateRecord may mean under-reporting. Aggregate usage BEFORE submitting so you never need to correct.
• Idempotent retries: Retrying the SAME record/quantity on a transient failure is safe (returns DuplicateRecord, harmless). Never retry to change a quantity — that will not work.
• 25-record batch limit + 1 MB request-size limit: Each BatchMeterUsage call accepts max 25 UsageRecords AND the total request payload must be ≤ 1 MB. These are two INDEPENDENT limits — a batch of ≤25 records can still be rejected for SIZE if the records are large (many/large usageAllocations tag-sets, long ARNs). If you have 25 valid records but the request is rejected for size, split into smaller batches (fewer records per call) so each request stays under 1 MB — it is the byte size, not the record count, that is over. Rate limit: 10 BatchMeterUsage requests/second per account per region (documented quota) — the serial submitter stays within it.

Why EventBridge (Not SNS) Is Required

The shift to CustomerAWSAccountId + LicenseArn also dictates which notification mechanism you must use:

The problem: Legacy SNS subscription notifications (subscribe-success, unsubscribe-success, etc.) identify the customer using CustomerIdentifier. But since new integrations must key everything on CustomerAWSAccountId, you cannot reliably match an SNS notification to a customer record keyed by CustomerAWSAccountId without an extra lookup/mapping step.

EventBridge events (Purchase Agreement Created, Purchase Agreement Ended, License Deprovisioned, etc.) include the buyer’s AWS account ID in the event detail, making them directly compatible with CustomerAWSAccountId-based customer records.

Bottom line: If you are building a new integration, use EventBridge only. Do not set up SNS subscription topics. This skill deploys an EventBridge-based events stack in us-east-1 for this reason.

Note for existing products migrating: If you currently use SNS and are migrating to CustomerAWSAccountId-based metering, you must also migrate your subscription event handling from SNS to EventBridge. Running both during migration is safe — just ensure your customer table can be updated by either path.

Fallback for Legacy Products

The path is chosen by the seller’s EXISTING integration, not by the ResolveCustomer response. ResolveCustomer returns a top-level LicenseArn for SaaS products regardless of whether the integration is old or new, so its response is NOT the signal for which path to use.

• New integrations always use the Concurrent Agreements pattern: CustomerAWSAccountId + LicenseArn per UsageRecord.
• Existing (legacy) integrations that already meter with ProductCode + CustomerIdentifier can continue on that path. For an existing seller, the skill must understand the seller’s current integration/code and support or migrate it — it does not force this skill’s reference register.py / metering-pipeline handlers onto them.

The reference metering pipeline (scripts/metering_core.py + scripts/submitter.py) defaults to the CA (LicenseArn) path. A ProductCode fallback branch exists only to support a seller whose stored records predate CA (identified by a non-ARN licenseArn value), NOT because ResolveCustomer returned no LicenseArn:

Deprovisioning / Final Metering

Two independent status fields track different lifecycles and are NOT conflated: agreementStatus (agreement) and subscriptionStatus (license). Metering decisions follow the license lifecycle only:

1. Purchase Agreement Ended — set agreementStatus = 'inactive' ONLY. This is a status update; it does NOT change subscriptionStatus, stop metering, or trigger a flush. The buyer may still be entitled to usage until the license is deprovisioned.
2. License Deprovisioned — set subscriptionStatus = 'deprovisioning' + a deprovisioningExpiry (event time + ~1h). This OPENS the ~1-hour final-usage flush window: submit any remaining usage IMMEDIATELY. The pipeline meters this row during the window; the events-stack deprovision-cleanup Lambda (rate(15m)) then sets subscriptionStatus = 'inactive' once deprovisioningExpiry has passed (time-based finalization — NOT the submitter). Once the server-side window closes, BatchMeterUsage returns CustomerNotSubscribed (a terminal status — do not retry).

Do not invert these. License Deprovisioned (not Purchase Agreement Ended) opens the flush window. Do NOT stop metering or flush on Purchase Agreement Ended, and do NOT discard queued records before flushing (that loses revenue). There is no deprovisioned status value — the license lifecycle is active → deprovisioning → inactive.