Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

BatchMeterUsage

To post metering records for customers, SaaS applications call BatchMeterUsage, which is used for metering SaaS flexible consumption pricing (FCP). Identical requests are idempotent and can be retried with the same records or a subset of records. Each BatchMeterUsage request is for only one product. If you want to meter usage for multiple products, you must make multiple BatchMeterUsage calls.

Usage records should be submitted in quick succession following a recorded event. Usage records aren't accepted 6 hours or more after an event.

BatchMeterUsage can process up to 25 UsageRecords at a time, and each request must be less than 1 MB in size. Optionally, you can have multiple usage allocations for usage data that's split into buckets according to predefined tags.

BatchMeterUsage returns a list of UsageRecordResult objects, which have each UsageRecord. It also returns a list of UnprocessedRecords, which indicate errors on the service side that should be retried.

For AWS Regions that support BatchMeterUsage, see BatchMeterUsage Region support.

Note

For an example of 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

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