BatchMeterUsage
BatchMeterUsage
is called from a SaaS application listed on AWS
Marketplace to post metering records for a set of customers.
BatchMeterUsage
is used for metering SaaS Flexible Consumption Pricing
(FCP). BatchMeterUsage
is supported in the following AWS Regions:
- Commercial Regions
-
eu-north-1, me-south-1, ap-south-1, eu-west-3, ap-southeast-3, us-east-2, af-south-1, eu-west-1,me-central-1, eu-central-1, sa-east-1, ap-east-1, ap-south-2, us-east-1, ap-northeast-2, ap-northeast-3, eu-west-2, ap-southeast-4, eu-south-1, ap-northeast-1, us-west-2, us-west-1, ap-southeast-1, ap-southeast-2, il-central-1, ca-central-1, eu-south-2, eu-central-2
- China Regions
-
cn-northwest-1
For identical requests, the API is idempotent; requests can be retried with the same records or a subset of the input records.
Every request to BatchMeterUsage
is for one product. If you need to meter
usage for multiple products, you must make multiple calls to
BatchMeterUsage
.
Usage records are expected to be submitted as quickly as possible after the event that is being recorded, and are not accepted more than 6 hours after the event.
BatchMeterUsage
can process up to 25 UsageRecords
at a
time.
A UsageRecord
can optionally include multiple usage allocations, to
provide customers with usage data split into buckets by tags that you define (or allow
the customer to define).
BatchMeterUsage
returns a list of UsageRecordResult
objects,
showing the result for each UsageRecord
, as well as a list of
UnprocessedRecords
, indicating errors in the service side that you
should retry.
BatchMeterUsage
requests must be less than 1MB in size.
Note
For an example of using BatchMeterUsage
, see BatchMeterUsage code example in the
AWS Marketplace Seller
Guide.
Request Syntax
{
"ProductCode": "string
",
"UsageRecords": [
{
"CustomerIdentifier": "string
",
"Dimension": "string
",
"Quantity": number
,
"Timestamp": number
,
"UsageAllocations": [
{
"AllocatedUsageQuantity": number
,
"Tags": [
{
"Key": "string
",
"Value": "string
"
}
]
}
]
}
]
}
Request Parameters
The request accepts the following data in JSON format.
Note
In the following list, the required parameters are described first.
- ProductCode
-
Product code is used to uniquely identify a product in AWS Marketplace. The product code should be the same as the one used during the publishing of a new product.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 255.
Pattern:
^[-a-zA-Z0-9/=:_.@]*$
Required: Yes
- UsageRecords
-
The set of
UsageRecords
to submit.BatchMeterUsage
accepts up to 25UsageRecords
at a time.Type: Array of UsageRecord objects
Array Members: Minimum number of 0 items. Maximum number of 25 items.
Required: Yes
Response Syntax
{
"Results": [
{
"MeteringRecordId": "string",
"Status": "string",
"UsageRecord": {
"CustomerIdentifier": "string",
"Dimension": "string",
"Quantity": number,
"Timestamp": number,
"UsageAllocations": [
{
"AllocatedUsageQuantity": number,
"Tags": [
{
"Key": "string",
"Value": "string"
}
]
}
]
}
}
],
"UnprocessedRecords": [
{
"CustomerIdentifier": "string",
"Dimension": "string",
"Quantity": number,
"Timestamp": number,
"UsageAllocations": [
{
"AllocatedUsageQuantity": number,
"Tags": [
{
"Key": "string",
"Value": "string"
}
]
}
]
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- Results
-
Contains all
UsageRecords
processed byBatchMeterUsage
. These records were either honored by AWS Marketplace Metering Service or were invalid. Invalid records should be fixed before being resubmitted.Type: Array of UsageRecordResult objects
- UnprocessedRecords
-
Contains all
UsageRecords
that were not processed byBatchMeterUsage
. This is a list ofUsageRecords
. You can retry the failed request by making anotherBatchMeterUsage
call with this list as input in theBatchMeterUsageRequest
.Type: Array of UsageRecord objects
Array Members: Minimum number of 0 items. Maximum number of 25 items.
Errors
For information about the errors that are common to all actions, see Common Errors.
- DisabledApiException
-
The API is disabled in the Region.
HTTP Status Code: 400
- InternalServiceErrorException
-
An internal error has occurred. Retry your request. If the problem persists, post a message with details on the AWS forums.
HTTP Status Code: 500
- InvalidCustomerIdentifierException
-
You have metered usage for a
CustomerIdentifier
that does not exist.HTTP Status Code: 400
- InvalidProductCodeException
-
The product code passed does not match the product code used for publishing the product.
HTTP Status Code: 400
- InvalidTagException
-
The tag is invalid, or the number of tags is greater than 5.
HTTP Status Code: 400
- InvalidUsageAllocationsException
-
Sum of allocated usage quantities is not equal to the usage quantity.
HTTP Status Code: 400
- InvalidUsageDimensionException
-
The usage dimension does not match one of the
UsageDimensions
associated with products.HTTP Status Code: 400
- ThrottlingException
-
The calls to the API are throttled.
HTTP Status Code: 400
- TimestampOutOfBoundsException
-
The
timestamp
value passed in theUsageRecord
is out of allowed range.For
BatchMeterUsage
, if any of the records are outside of the allowed range, the entire batch is not processed. You must remove invalid records and try again.HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: