Quickstart

Quickly set up Metronome and generate your first usage-based invoice by following these essential steps. If testing your Metronome environment for the first time, make sure to follow these steps in the Metronome sandbox environment as opposed to production.

1. Design usage events

Usage events in Metronome are structured records that capture specific actions or activities performed by customers that are relevant for usage-based billing. Events can represent:

• Discrete actions such as a single API call, file upload, or data query.
• Aggregated heartbeats which track continuous or repeated usage over time and report the total usage during a specific interval. For example, a heartbeat event could represent total storage used in an hour or the total number of API requests over a day.

To track customer activities accurately and ensure proper billing, each usage event in Metronome must contain certain required fields. These include:

• timestamp, when the usage occurred
• transaction_id, used to ignore duplicate events
• customer_id, a unique identifier for the customer or account associated with the event
• event_type, describes the details of the event, along with the properties field
• properties, additional key-value pairs that provide context for the event, such as metadata about the usage or customer activity

To get started, below are two simplified versions of usage events that correspond to metrics clients commonly track.

AI image generation

In the AI space, image generation requests are often priced based on the number of images generated, image resolution, and complexity of the prompt. For example, a single 1024x1024 image may have a different cost than a 512x512 image. When defining an event format to meter the number of images of each resolution generated, we want to include the resolution along with the number of images generated as metadata in the properties JSON. Additional metadata that does not influence pricing, but which you may want present a breakdown of usage by, such as the model used in the image generation, can also be passed in the properties.

{
  "timestamp": "2024-09-27T00:00:00+00:00",
  "transaction_id": "0a167631-4c07-49f2-b6ef-c1f91a1325e1",
  "customer_id": "quickstart-demo",
  "event_type": "image_generation",
  "properties": {
    "resolution": "1024x1024",
    "model": "DALL-E 2",
    "num_images": "3"
  }
}

Database as a Service (DBaaS) storage

Many DBaaS providers charge based on the volume of data stored throughout the billing period, often aggregating the high-water marks for each table or cluster during the month. For this scenario, events should contain properties specifying the table/cluster the measurement is for along with the amount of data stored. Data volumes could be passed in kilobytes, megabytes, gigabytes, and so on. Metronome can convert these quantities for you to adjust your invoice presentation.

{
  "timestamp": "2024-09-21T02:00:00+00:00",
  "transaction_id": "c012f5c8-e0a3-46ec-b4b4-9bf64949a352",
  "customer_id": "quickstart-demo",
  "event_type": "storage_heartbeat",
  "properties": {
    "cloud": "aws",
    "cluster_id": "b1600b4c-ef72-4b67-bc27-eaccad4cbed2",
    "table_id": "6820fb25-d381-488b-9e7a-261186d5ddd1",
    "region": "us-west-1",
    "mb_stored": "3000"
  }
}

2. Send test events

After designing the appropriate usage events for your integration, you can begin sending them to Metronome. Simply call the API using your API token.

Create an API token

API tokens can be created in the Metronome app:

1. Click on Connections in the navigation bar.
2. Click on API tokens & webhooks in the horizontal navigation bar on the resulting page.
3. Click on the + Add button.
4. Enter a descriptive name for the token and click Create new token.
5. Copy the token string to a secure location before clicking Done.

info

Be sure to copy and save the token before closing the dialog box as you cannot retrieve the full token after clicking Done. If you lose an API token, you must create a new one.

Call the /ingest endpoint

Using the API token you just created, you can now send Metronome some example events. This can be easily done using a cURL command to the /ingest endpoint. Structure your request like the example shown below, replacing <TOKEN> with your key.

info

See the /ingest API reference and the Metronome SDKs for additional syntax examples for HTTP, Python, Go, and Node.js requests.

curl https://api.metronome.com/v1/ingest \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "timestamp": "2024-09-27T00:00:00+00:00",
      "transaction_id": "0a167631-4c07-49f2-b6ef-c1f91a1325e1",
      "customer_id": "quickstart-demo",
      "event_type": "image_generation",
      "properties": {
        "resolution": "1024x1024",
        "model": "DALL-E 2",
        "num_images": "3"
      }
    },
    {
      "timestamp": "2024-09-21T02:00:00+00:00",
      "transaction_id": "c012f5c8-e0a3-46ec-b4b4-9bf64949a352",
      "customer_id": "quickstart-demo",
      "event_type": "storage_heartbeat",
      "properties": {
        "cloud": "aws",
        "cluster_id": "b1600b4c-ef72-4b67-bc27-eaccad4cbed2",
        "table_id": "6820fb25-d381-488b-9e7a-261186d5ddd1",
        "region": "us-west-1",
        "mb_stored": "3000"
      }
    }
  ]'

A 200 response indicates payloads were properly formatted and Metronome has accepted the events. You can also validate the sample events were processed by viewing the Events page in the Metronome app. This can be found by clicking on Connections in the navigation bar and then clicking on the Events tab.

tip

If you're creating a streaming billable metric, you need to set up your billable metric first for usage to count against it.

3. Define billable metrics

Billable metrics aggregate customer usage of your product, such as the number of API calls made or volume of data processed, to determine the quantity for which your customers should be charged. Billable metrics are tracked continuously as events enter the system to power real-time usage dashboards and alerting.

Metronome supports two types of billable metrics:

• Streaming billable metrics are defined using basic filters to match usage events
• SQL billable metrics use a SQL editor input, allowing for more complex filtering

Below are two billable metrics for the sample usage events defined above.

AI image generation

Use the Metronome app to set up a streaming billable metric for 1024x1024 image generation.

1. Click on Offering in the navigation bar.

2. Click on Billable metrics in the horizontal navigation bar on the resulting page.

3. Click + Add.

4. Leave Basic filters selected as the Define metric with type.

5. Name your metric (for example, Image Generation 1024x1024).

6. In the Select event type section, leave the filter as In and enter the event_type (s) which you're passing in the usage events. In the AI example above, this is “image_generation”. Press enter or click on the event type name in the dropdown to save the value.

7. Click the + Add property filter button to add a new filter. Enter the property name, select the filter type from the dropdown (In, Not in, Exists, Does not exist), and enter one or more values if using the In or Not in filters. Repeat this step for each additional property filter that should be applied. The screenshot below provides an example of what these filters would look like based on the example AI event provided earlier in this Quickstart guide:

   

8. Select the metric’s aggregation type in the Aggregate by section. If using SUM, MAX, or UNIQUE aggregation types, select the property name containing the data which should be metered.

9. Optionally set group keys.

10. Click Save.

info

When configuring streaming billable metrics, paste a sample event into the Example event payload box to validate you have correctly defined the filters.

DBaaS storage

Use the Metronome app to set up a SQL billable metric for metering database storage usage. SQL billable metrics are better suited to this scenario due to the additional logic to calculate the sum of the maximum storage consumed across all tables across the billing period.

1. Click on Offering in the navigation bar.

2. Click on Billable metrics in the horizontal navigation bar on the resulting page.

3. Click + Add.

4. Select SQL query as the Define metric with type.

5. Write a SQL query to return the max storage used for each table over the course of the billing period. Press Run to test and validate the query. The screenshot below provides an example of what the query would look like based on the example DBaaS event provided earlier in this Quickstart guide:

   

6. Click Save.

4. Create products

A product is anything a customer can purchase. Products defined in Metronome dictate:

• How a customer is charged for a product. Products can be usage-based, composite (of multiple usage-based products), subscription-based, or fixed.
• How a product is displayed on an invoice. This comes from the product's name. Each product becomes a single line item on an invoice.

There are four product types:

• Usage: variably priced based on reported customer usage for the period (reported through usage events). Event matching and aggregation is determined by the product’s underlying billable metric.
• Subscription: a recurring, prorated fixed fee, billed on a schedule.
• Composite: percentage charge on a group of applicable products.
• Fixed: used to power scheduled charges like commits and credits or other fees.

The sections below walk through creating two of the four product types for the AI image generation and DBaaS scenarios.

Create usage-based products

To create the product for the AI image generation example:

1. Click on Offering in the navigation bar.
2. Click on the Products tab in the horizontal navigation bar on the resulting page.
3. Click + Add new product.
4. Enter a Name for the product. Note that this name is customer-facing and appears on the corresponding invoice line item.
5. Select Usage as the product type.
6. Find and select the Image Generation billable metric created previously.
7. Click Save.

To create the product for the DBaaS storage example, follow the same steps, this time selecting the Storage SQL billable metric created. Before saving, click the toggle next to Convert quantity to add conversion logic. In the sample payload defined earlier in the Quickstart, the storage units were sent in megabytes. However, you may prefer to present to customers in gigabytes instead. Quantity conversions allow you multiply or divide the product quantities by a numerical factor. To convert to GB, select Divide quantity, enter 1024 in the Conversion factor field, and optionally add a descriptive Conversion name.

Create composite products

Composite charges are based on the total of other charges (products), such as a support fee based on a percentage of overall spend for usage-based products.

To create a support fee:

1. Follow steps 1-4 outlined in the usage-based products section above to begin creating a new product.
2. Select Composite as the product type.
3. Find and select the Image Generation and Storage usage products from the list under Select the applicable products or tags.
4. Click Save.

5. Create a rate card

Rate cards establish the default product prices and availability, which can be tweaked on a per-contract basis. Rate cards only apply to usage-based, composite, and subscription products; prices on fixed products are set directly on the contract.

1. Click on Offering in the navigation bar.
2. Click the + Add new rate card button.
3. Enter a Rate card name and optionally enter a Rate card description.
4. In the products section, select the usage-based products and composite product created previously and click Continue.
5. Rate the usage products:
   1. Starting at: inclusive start date for the rate.
   2. Ending before (optional): exclusive end date for the rate.
   3. Default entitlement: whether the rate is enabled or disabled by default on contracts. Leave as Enabled.
   4. Rate: the per-unit price. Enter a rate, e.g. 0.1 for $0.10 per unit.
   5. Pricing unit: the currency of the charge. Leave as USD.
6. Rate the composite product. In the table below the usage products, fill out the following fields for the composite product:
   1. Starting at: inclusive start date for the rate.
   2. Ending before (optional): exclusive end date for the rate.
   3. Default entitlement: whether the rate is enabled or disabled by default on contracts. Leave as Enabled.
   4. Rate: for composite products, the rate is defined as a percentage of the total spend of the applicable products. Enter a value for the rate, such as 5, to charge a 5% fee based on the usage-based product spend.
7. Click Save.

6. Create a customer

In Metronome, a customer is an entity (individual, organization, or account) that uses your product or service and for whom you're tracking usage and generating invoices. Customers are at the core of Metronome’s billing system, as all usage events, contracts, and invoices are tied to specific customers.

1. Click on Customers in the navigation bar.
2. Click the + Add button.
3. Enter the Customer Name.
4. Click Add new customer to save.

7. Provision a contract

A contract determines a customer's products, pricing schedules, committed spending, and more. The steps below walk through a simple contracting scenario: a 1-year list-price contract with a prepaid commit.

1. Click on Customers in the navigation bar and select the customer created previously.

2. On the Billing overview tab, click on the + Add button on the right hand side of the contracts pane.

3. Fill in the basic Contract details:

   1. Contract name: an optional display name for the contract in the Metronome app.

   2. Rate card: the rate card the contract is based off of. Select the rate card created previously.

   3. Starting at: inclusive start date for the contract. Leave as the current date or optionally select a date in the past.

   4. Ending before (optional): exclusive end date for the contract. For a 1-year contract, select the same month and day as the Starting at in the following year.

   5. Usage statement frequency: the duration of the billing period (or how often an invoice is generated). Leave this as Monthly.

   6. Usage statement day: when the billing period starts. Leave as First of month.

      

4. Add the prepaid commit to the contract by clicking the + Add a commit button. Fill in the basic required Commit details:

   1. Commit product: the fixed product that represents the commit. Select the Prepaid Commit product created previously.

   2. Description (optional): internal description of the commit.

   3. Applicable products / Applicable tags (optional): limits which products’ usage burns down the commit. If left blank, the commit applies to all enabled products on the contract rate card. Leave both fields blank for now.

   4. Commit type: whether prepaid or postpaid. Select Prepaid from the dropdown.

      

5. Define the commit’s Access schedule. For prepaid commits, the access schedule contains one or more segments that define how much prepurchased usage (or credit) the customer can consume before paying overages and a time window for when the segment is available to be consumed. For example, a customer on a 1-year contract may have a single segment with Starting at and Ending before dates that correspond to the start and end dates of the contract - meaning the customer has access to the full commit immediately at the beginning of the contract. For information on how commits get applied, review Apply credits and commits.

   

6. Define the commit’s Invoice schedule. For prepaid commits this determines how the customer pays for their commitment - whether all at once or broken up into installments. For the simple 1-year scenario, this may be a single, one-time invoice for the total amount. The invoice schedule also determines the cost basis for any prepurchased credits (if the total invoiced equals the total amount in the access schedules, then there is a 1:1 cost-basis).

   

7. Specify a Priority for the commit. The priority determines which order commits are applied (if there are multiple active commits or credits), with lower priorities taking precedence.

8. Click Add to save the commit.

9. Leave all other configurations as is and click Save.

Congratulations! After completing the Quickstart you've generated your first invoice. Navigating to the customer page, you'll see the scheduled invoice for the prepaid commit payment installation along with the draft usage invoice used to meter the customer.