Create a Metering Record

Before you get started

You'll need to make sure you have the correct listing type and usage-based SKUs configured, along with your Access Token

Send a Usage Record

The endpoint for submitting these usage records is https://api.tackle.io/v1/metering/usage-records. We recommend you use the PUT method, but we do support both PUT and POST.

PUT

Using the PUT method will create or update an existing usage record (if it hasn't already been sent to the marketplace).

If a usage record already exists in Tackle's system for the submitted product, dimension, customer and hour (from start_time), we will update the quantity on the existing record. If the record has already been submitted to the marketplace, the API will respond with a 409 - Conflict response.

POST

Using the POST method will create a new usage record.

Caution: If you submit duplicate usage records for the same product, dimension, customer and hour (from start_time), only one of the submitted records will be sent to the marketplace: we do not aggregate submitted records.

First time testing this functionality? See the Testing section below.

Send the request with the right authorization header and body similar to the following example:

{
  "cloud": "aws",
  "product_id": "e2fc31adc8dc32e281e3a6c27d003d7c",
  "customer_id": "6182cde02709282f5baf7329",
  "start_time": "2021-12-09 18:31:12.789942",
  "dimension": {
    "name": "Metering-Test-Charge-1-Users",
    "quantity": 42
  }
}

{
  "cloud": "gcp",
  "product_id": "e2fc31adc8dc32e281e3a6c27d003d7c",
  "customer_id": "6182cde02709282f5baf7329",
  "start_time": "2021-12-09 18:31:12.789942",
  "end_time": "2021-12-09 18:35:12.789942",
  "dimension": {
    "name": "Metering-Test-Charge-1-Users",
    "quantity": 42
  }
}

 {
  "cloud": "azure",
  "product_id": "e2fc31adc8dc32e281e3a6c27d003d7c",
  "customer_id": "6182cde02709282f5baf7329",
  "start_time": "2021-12-09 18:31:12.789942",
  "dimension": {
    "name": "Metering-Test-Charge-1-Users",
    "quantity": 42
  }
}

Testing

To test a usage record without the risk of sending it to the marketplace, you need to include the test attribute in the usage record payload. You can test a usage record by passing in one of the options accepted, rejected, or not-operable to the test flag.

{
  "cloud": "aws",
  "product_id": "e2fc31adc8dc32e281e3a6c27d003d7c",
  "customer_id": "6182cde02709282f5baf7329",
  "start_time": "2021-12-09 18:31:12.789942",
  "dimension": {
    "name": "Metering-Test-Charge-1-Users",
    "quantity": 42
  },
  "test": "accepted"
} 

Test attribute with accepted value

The usage record will be updated with a status of accepted, without actually being sent to the marketplace.

Test attribute with rejected value

The usage record will be updated with a status of rejected and a reason of invalid-usage-dimension, mocking a scenario where the marketplace rejected a usage record due to an invalid usage dimension being provided.

Test attribute with not-operable value

The usage record will be updated with a status of not-operable and a reason of external-access-denied, mocking a scenario where a usage record failed to submit to the marketplace due to invalid credentials.

Refer to the API reference to see a more robust example response.

How to confirm usage records have been sent?

To see what metering records are present, see List Usage Records.

To see a specific usage record, see Get a Usage Record.

You can also use the Downstream Metering UI, looking for a green checkmark next to the submitted usage. If a record failed, it will have a red circle with an 'x'. If you hover over it, you a description will be provided as to why the submission failed.