Test your integration

Once you've set up your usage events, billable metrics, and pricing, you're ready to test your Metronome integration end-to-end. This is the last step before going live.

Review security guidelines

Metronome's service is built based on three fundamental security principles:

• Principle of least privilege. Every actor in Metronome has access to no data and the ability to take no actions until that access has been explicitly granted.
• Zero-trust architecture
• No access granted through long-lived credentials or configuration

Metronome recommends reviewing key security factors while testing your integration.

• Authentication: Metronome supports SSO with the SAML 2.0 protocol, both for service provider and identity provider initiated authentication. We strongly recommend that SSO is configured and that multi-factor authentication (MFA) is enabled at the SSO identity provider level (Okta) when accessing Metronome.
• Authorization: All calls to the Metronome API require an authorization token. You can create a token and give it a friendly name in the Metronome app.
  • Metronome strongly recommends that API tokens are stored in a Secrets Manager that supports programmatic access.
  • Metronome suggests that customers rotate API tokens based on their internal security policy. We typically recommend that customers rotate API tokens once a year or after any security incident.
• End-user data: User accounts in Metronome are associated with emails, but we do not require or store additional personally identifiable information (PII). Metronome also requires some pricing and packaging inputs to generate invoicing and cost data. Customer information can be obfuscated using ingest aliases.

Create a test customer

As part of your test, you produce and ingest test usage events. Usage events in Metronome are always attributed to a customer, so first you create a new test customer.

Give 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"}'

Save the value of the external_id field returned by this call to complete the testing steps.

To generate invoices, 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 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>"}'

Send usage events

Next, send usage events to the /ingest endpoint. The structure of your usage events depends 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 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. Make sure the total data transfer in your test data exceeds 1000GB to 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. Use the customer ID you created in the previous step and format your timestamps according to RFC 3399 (2021-03-01T12:34:56Z). Remember 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": {
      "region": "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. See Getting usage data into Metronome to help identify the problem, or contact your Metronome representative.

Check the invoice

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

Call the /customers/{customer_id}/invoices 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:

• Usage was aggregated correctly. Check that duplicate events were ignored and that the quantity field matches what you expect.
• Pricing was 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 something looks incorrect, contact your Metronome representative for help debugging.

Test grouped metrics (optional)

If any of your billable metrics are grouped, you can test grouping by using the /usage 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.