AWS Marketplace Metering Errors — The Plain-English Guide¶
Source: Vellocity's Metered Billing Diagnostics — auto-diagnoses BatchMeterUsage failures with fix steps partners can act on immediately.
Field context: In Q1 2026, 112 AWS partners submitted 295 prompts to the AWS Virtual Partner Assistant about SaaS metering configuration and integration errors. This guide answers those questions directly.
How to Use This Guide¶
If your metered billing submission fails, find the AWS error code in the list below. Each entry explains:
- What happened — plain-English summary
- Why it happened — the most common causes
- How to fix it — numbered steps you can take right now
- Can you retry? — whether submitting the same batch again will help
Inside Vellocity, these explanations appear automatically on the Metered Billing Diagnostics page. You can also share a diagnostic link directly with AWS Support — no copy-paste, no re-explaining.
The Errors¶
1. InvalidCustomerIdentifierException¶
Severity: Blocker | Retryable: No
What happened: The customer_identifier on your metering record does not match any customer in AWS Marketplace for your product.
Why it happened:
- Customer unsubscribed from the product before this usage was metered
- The customer_identifier was copied from a different product listing
- Usage was tracked against a preview/test customer that does not exist in AWS
- A typo or encoding issue when the customer was originally onboarded
How to fix it:
1. Confirm the customer is still subscribed: check the Entitlements page for their customer_identifier
2. If they unsubscribed, this usage should be written off — mark the batch as won't-fix
3. If they are still subscribed, re-resolve the customer via ResolveCustomer with a fresh registration token
4. Make sure the product_code on the record matches the listing the customer subscribed to
AWS docs: BatchMeterUsage Errors
2. DuplicateRequestException¶
Severity: Info (safe to ignore) | Retryable: No
What happened: AWS already received a metering record for this customer, product, dimension, and timestamp combination. Metering is idempotent on these four fields.
Why it happened: - The metering command ran twice for the same period (overlapping cron invocations) - A previous run succeeded but its response was lost — AWS saw it, you did not - Timestamps were rounded to the same bucket across two distinct submissions
How to fix it:
1. Safe to ignore — AWS has already recorded the usage
2. Mark the local batch as accepted if the original submission timestamp matches
3. Check your cron schedule for overlapping runs — consider adding withoutOverlapping() to the schedule
4. Never attempt to "fix" this by changing the timestamp — that creates a real double-bill
AWS docs: BatchMeterUsage Errors
3. TimestampOutOfBoundsException¶
Severity: Blocker | Retryable: No
What happened: AWS Marketplace only accepts usage records with a timestamp within the last 6 hours. This record is either too old or dated in the future.
Why it happened:
- Metering command was paused or failed for more than 6 hours — backlog aged out
- Host clock is drifting (NTP out of sync)
- period_end on the usage record was set to a future timestamp
- The job was queued but not dispatched for hours
How to fix it:
1. Check the host clock: run date -u and compare to a reliable time source
2. For the aged-out records, this usage cannot be billed — mark the batch won't-fix and investigate the delay
3. Fix the root cause of the metering delay before retrying
4. Add monitoring/alerting on your metering command so you catch stalls within the 6-hour window
AWS docs: BatchMeterUsage Errors
4. InvalidUsageDimensionException¶
Severity: Blocker | Retryable: No
What happened: The dimension on this record does not match any of the metered dimensions you declared in your AWS Marketplace product listing.
Most common error
This was the #1 specific error cited in the Q1 2026 Partner Assist analysis. Example prompt: "Dimension with key 'Starter_Trip_Usage' for productCode has no metering record present in Metering Service"
Why it happened: - Dimension name changed in code but the listing was never updated - Listing was updated with a new dimension but the old one is still in the database - Typo or capitalization mismatch — dimensions are case-sensitive - Using a free-tier dimension on a paid customer or vice versa
How to fix it: 1. Check the dimensions declared on your listing: AWS Marketplace Management Portal → Products → Your product → Dimensions 2. Compare against the dimension constants in your codebase 3. If the listing is authoritative, update the code to match exact spelling/casing 4. If the code is authoritative, submit a listing change in AWS Marketplace to add the missing dimension
AWS docs: BatchMeterUsage Errors
5. InvalidProductCodeException¶
Severity: Blocker | Retryable: No
What happened: The product_code on this metering record does not match any product your AWS account is registered to sell.
Why it happened:
- product_code was copied from a different seller's listing
- Listing was moved to a new AWS account but the code was not updated in the database
- Record was created against a development/sandbox product that does not exist in production
How to fix it:
1. Check the authoritative product_code in your AWS Marketplace Management Portal
2. Update the record's product_code and retry (if the subscription is still valid)
3. If the product was deprecated, mark the batch won't-fix
AWS docs: BatchMeterUsage Errors
6. InvalidEndpointRegionException¶
Severity: Blocker | Retryable: No
What happened: AWS Marketplace Metering Service is only available in us-east-1. You are calling it from a different region.
Why it happened:
- AWS_DEFAULT_REGION is set to something other than us-east-1
- The metering client was constructed with a different region
How to fix it:
1. Set the metering client region explicitly to us-east-1, regardless of AWS_DEFAULT_REGION
2. Do NOT change AWS_DEFAULT_REGION globally — other services depend on it
3. Verify by searching your codebase for MarketplaceMetering and checking each client instantiation
AWS docs: AWS Marketplace Endpoints
7. ThrottlingException¶
Severity: Warning | Retryable: Yes
What happened: You submitted too many BatchMeterUsage requests too quickly and AWS is throttling your account.
Why it happened: - Metering command is running more often than hourly (the recommended cadence) - A one-off backfill is submitting many batches without backoff - Parallel workers are all submitting at once
How to fix it:
1. Retry the batch with exponential backoff — these errors are transient
2. Reduce the frequency of your metering command to at most hourly
3. Serialize concurrent workers with a lock or withoutOverlapping()
AWS docs: Common Errors
8. InternalServiceErrorException¶
Severity: Warning | Retryable: Yes
What happened: AWS Marketplace had a transient server-side issue when processing this batch. This is not a problem with your data.
Why it happened: - Temporary AWS-side degradation - Maintenance window
How to fix it: 1. Retry the batch — these errors usually resolve themselves within minutes 2. If retries keep failing, check the AWS Service Health Dashboard for Marketplace incidents 3. Do not modify the usage data — the failure is on AWS's side
AWS docs: Common Errors
9. ExpiredTokenException¶
Severity: Warning | Retryable: Yes
What happened: The IAM credentials used to submit metering expired before the call completed.
Why it happened: - Assumed IAM role session expired (default 1 hour) - Long-running command held credentials across the session boundary
How to fix it:
1. Retry the batch — fresh credentials will be acquired on the next run
2. If using an assumed role, increase DurationSeconds or re-assume closer to the metering call
AWS docs: STS Common Errors
10. AccessDeniedException¶
Severity: Blocker | Retryable: No
What happened: The IAM principal making the request does not have the aws-marketplace:BatchMeterUsage permission.
Why it happened:
- IAM policy missing aws-marketplace:MeterUsage or aws-marketplace:BatchMeterUsage
- Resource-level restriction scoped to a different product code
- Policy boundary blocking marketplace actions
How to fix it:
1. Add the aws-marketplace:BatchMeterUsage action to the IAM role's policy
2. Ensure the resource ARN allows all product codes: arn:aws:aws-marketplace:*:*:product/*
3. Check for IAM permission boundaries or SCPs that might be denying marketplace actions
4. Test with: aws marketplace-metering batch-meter-usage --dry-run
AWS docs: IAM for AWS Marketplace Actions
SaaS Contract vs. SaaS Subscription¶
Why this matters
The Q1 2026 Partner Assist analysis found that confusion between SaaS contracts and SaaS subscriptions is a top theme alongside metering errors. This section explains the difference.
SaaS Subscriptions (Pay-As-You-Go)¶
- Buyer subscribes and pays based on actual usage each billing cycle
- You meter usage via
BatchMeterUsageAPI — AWS bills the buyer - No upfront commitment from the buyer
- Revenue recognized as usage occurs
- When to use: Products with variable consumption (API calls, storage, users)
SaaS Contracts (Prepaid Entitlements)¶
- Buyer commits to a fixed quantity upfront for a contract term (1, 2, or 3 years)
- You verify entitlements via
GetEntitlementsAPI — no per-usage metering needed - Buyer pays upfront or in installments
- Revenue recognized over the contract term
- When to use: Products with predictable, seat-based, or tiered pricing
The Hybrid: SaaS Contracts with Consumption¶
- Buyer commits to a base entitlement (e.g., 1000 API calls/month)
- Usage beyond the entitlement is metered via
BatchMeterUsage - Combines the predictability of contracts with the flexibility of pay-as-you-go
Where most errors happen
Partners confuse which dimensions are contract-based (checked via GetEntitlements) vs. consumption-based (reported via BatchMeterUsage)
How to Tell Which Model You're Using¶
| Question | SaaS Subscription | SaaS Contract |
|---|---|---|
| Does the buyer commit upfront? | No | Yes (1-3 year term) |
| How does billing work? | You meter → AWS bills | Buyer pays upfront or installments |
| Which API do you call? | BatchMeterUsage |
GetEntitlements |
| Can the buyer cancel anytime? | Yes (monthly) | At contract renewal |
| Where do dimension errors happen? | BatchMeterUsage call |
GetEntitlements returns 0 |
Common Mistakes¶
- Calling
BatchMeterUsagefor contract dimensions — AWS returnsInvalidUsageDimensionExceptionbecause contract dimensions aren't metered, they're entitled - Not calling
GetEntitlementsbefore granting access — buyer's contract may have expired or they may have downgraded - Mixing pricing models across dimensions — some dimensions can be contract-based while others are consumption-based on the same listing, but each dimension must use ONE model
- Testing with the wrong product code — sandbox product codes don't carry over to production
About Vellocity's Metered Billing Diagnostics¶
Vellocity automatically diagnoses BatchMeterUsage failures with:
- Plain-English error explanations for every known AWS Marketplace Metering error code
- AI-powered diagnosis for unknown errors using Claude on AWS Bedrock
- One-click retry for transient errors (ThrottlingException, InternalServiceError, ExpiredToken)
- Shareable diagnostic links — send a tokenized URL to AWS Support so they can see the full error context without you re-explaining
Access the diagnostics console at Dashboard → Marketplace GTM Ops → Usage Dashboard → Diagnostics, or look for the red "failures need attention" badge on the Metering Health widget on your main dashboard.