Testing your Metronome integration

Once you've worked with the Metronome team to set up your usage events, billable metrics, and pricing, it's time to test your Metronome integration end to end. This document will walk you through a simple test process with the goal of catching configuration problems as early as possible.

This guide is aimed at engineers in the process of implementing a Metronome integration. In addition to reading the linked documents above, this is a good time to read the API authorization documentation so you're ready to make calls to the API.

Step 1: Create a test customer

As part of your test, you're going to be producing and ingesting test usage events. Usage events in Metronome are always attributed to a customer, so in this first step, you'll create a new customer to use for the rest of the tests. We recommend giving the customer a name that indicates it's for testing purposes only. Run the following curl command, substituting in your API token:

curl "https://api.metronome.com/v1/customers" \
-H "Authorization: Bearer <TOKEN>" \
-d '{"name": "TEST CUSTOMER"}'

Note the value of the external_id field returned by this call. You'll need to use this in the rest of the steps to refer to the correct test customer.

For invoices to be produced, customers in Metronome must have a plan. Once you've set up your product(s) and at least one plan, you can add that plan to your customer using the /customers/{customer_id}/plans/add API endpoint:

curl "https://api.metronome.com/v1/customers/<TEST CUSTOMER ID>/plans/add" \
-H "Authorization: Bearer <TOKEN>" \
-d '{"plan_id": "<TEMPLATE ID>", "starting_on": "<DATE>"}'

Step 2: Send usage events

As a first step, you'll send usage events to the /ingest API endpoint. The exact shape of your usage events depend on what you've designed with the help of the Metronome team.

We recommend sending at least three usage events, with one having a duplicate transaction ID. The duplicate should be ignored, and the usage from the other two events should be aggregated according to your defined billable metric(s). If you have more than one billable metric, you should send two events per metric to verify each one is working properly.

Testing tiered pricing

If you use tiered pricing, you'll gain the most information by ingesting usage events that trigger all the possible tiers. For example, consider tiered pricing where customers pay $0.10/GB for the first 100GB of data transfer, $0.09/GB for the next 900GB, and $0.08/GB beyond that. It's a good idea to make sure the total data transfer in your test data exceeds 1000GB. This way you can verify that every pricing tier is correctly defined.

The following curl command follows the example usage events in Getting usage data into Metronome, but your payload should match your actual usage events. Be sure to use the customer ID you created in the previous step and to format your timestamps according to RFC 3399, e.g. 2021-03-01T12:34:56Z. Note that the first event is intentionally sent twice to test duplicate events:

curl "https://api.metronome.com/v1/ingest" -H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '[
  {
    "customer_id": "<TEST CUSTOMER ID>",
    "transaction_id": "test1",
    "timestamp": "<TIME>"
    "event_type": "transfer",
    "properties": {
      "data_center": "US-WEST-3",
      "bytes": "5000",
    }
  },
  {
    "customer_id": "<TEST CUSTOMER ID>",
    "transaction_id": "test2",
    "timestamp": "<TIME>"
    "event_type": "transfer",
    "properties": {
      "region": "US-EAST-1",
      "bytes": "1000"
    }
  },
  {
    "customer_id": "<TEST CUSTOMER ID>",
    "transaction_id": "test1",
    "timestamp": "<TIME>",
    "event_type": "transfer",
    "properties": {
      "region": "US-WEST-3",
      "bytes": "5000",
    }
  }
]'

Metronome should respond to this call with a 200 status code. If you receive a 400 response, it means that something is wrong with your event payload. Consult Getting usage data into Metronome to see if you can spot the problem, or contact your Metronome representative for help.

caution

Property names and values are case-sensitive

Step 3: Check the invoice

There are several steps in the Metronome pipeline after event ingestion, but the easiest way to verify that everything is working is to look at the invoice produced at the end.

Call the /invoices API endpoint:

curl "https://api.metronome.com/v1/customers/<TEST CUSTOMER ID>/invoices?status=DRAFT" \
-H "Authorization: Bearer <TOKEN>"

The first invoice in the response should correspond to the usage data sent in the previous step, as in this example:

{
  "data": [
    {
      "status": "DRAFT",
            // ...
      "line_items": [
        {
          "name": "transfer",
          "quantity": "6000",
          "total": 0.60
        }
      ],
    }
  ],
  "next_page": null
}

Check each value in the line_items array for the following:

1. Was usage aggregated correctly? Check that duplicate events were ignored and that the quantity field matches what you expect.
2. Was pricing applied correctly? Verify that the total field is what you expect based on the quantity, including the correct application of tiered pricing, if applicable.

If things don't look right, work with a Metronome representative to debug further.

Step 4: Testing grouped metrics (optional)

If any of your billable metrics are grouped, you can test grouping by using the /usage API endpoint. The following curl command queries the list of billable metrics, including their available group_by keys:

curl "https://api.metronome.com/v1/customers/<TEST CUSTOMER ID>/billable-metrics" \
-H "Authorization: Bearer <TOKEN>"

Find your billable metric ID there, and call /usage with the group_by parameter to verify that the totals are correct. See Designing billable metrics for a complete example.

Next steps

Once you've successfully tested your Metronome integration, your Metronome representative can help you plan for sending production usage data and testing external invoicing, if applicable.