Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

BatchMeterUsage

BatchMeterUsage is called from a SaaS application listed on AWS Marketplace to post metering records for a set of customers.

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 25 UsageRecords 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 by BatchMeterUsage. 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 by BatchMeterUsage. This is a list of UsageRecords. You can retry the failed request by making another BatchMeterUsage call with this list as input in the BatchMeterUsageRequest.

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

The usage allocation objects are invalid, or the number of allocations is greater than 500 for a single usage record.

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 the UsageRecord 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