[ Web Proxy ]
URL:
Viewing: https://docs.metronome.com/guides/get-started/developer-sdks [Back]  [Original]

Build with the Metronome SDKs - Metronome
Skip to main content
Search...
Navigation
GET STARTED
Build with the Metronome SDKs
GET STARTED

Build with the Metronome SDKs

Copy page
Metronome provides powerful software development kits (SDKs) designed to seamlessly integrate Metronome billing APIs into your applications. The SDKs for Python, Go, Ruby, Node.js, and Java offer developers flexible options for implementing Metronomes capabilities across platforms and environments. This page walks through a basic but powerful usage-based billing system in Python, Node, Ruby, or Golang:
  1. Install and configure the Metronome SDK.
  2. Send usage events to Metronome, laying the foundation for consumption-based billing.
  3. Create a billable metric to define how Metronome should aggregate and measure usage.
  4. Create a customer in the system and associate them with usage events.
  5. Set up pricing and packing for your product.
  6. Create a contract for the customer, enabling automatic invoice generation based on their usage.

SDK features

Each SDK GitHub repository contains detailed documentation, examples, and resources to help you make the most of Metronome in your applications: Core SDK features include:
  • Strong typing of Metronome endpoints and objects enhance developer productivity with better autocomplete and IDE support for Metronome objects.
  • Pagination support simplifies the process of retrieving and managing paginated data from Metronome services.
  • Automatic retry support by default retries each request upon failure up to three times. You can configure it to any number of retries. Use this to automatically handle transient errors and network issues without needing to implement retry logic.
While this guide covered the fundamentals, Metronome offers much more functionality to model different business models. Check out the SDK repo to see whats possible.

1. Install and configure the SDK

First install and configure the SDK in your environment:
Next, configure the SDK by passing a valid API key as the authorization bearer token. By default, the SDK looks for the API key under the environment variable METRONOME_BEARER_TOKEN. In this example, itll be passed as an argument to the constructor instead.

2. Send usage events

The usage-based billing model builds upon captured usage data from users on your platform. Metronome accepts usage payloads of all formats through the /ingest endpoint. Use the SDK to send data to Metronome:
The properties used in this example include:
  • usage, allows you to pass in multiple event payloads in a request. Metronome supports passing up to 100 events within a single request.
  • transaction_id, provides Metronome with the unique idempotency key for the event. Metronome deduplicates based on this ID, allowing you to send events potentially many times without worrying about double-charging your customers.
  • timestamp, the time when the event occurred. Send in events with any timestamp up to 34 days in the past.
  • customer_id, the customer ID in Metronome or any other customer identifier you want to define. For example, customer email or internal customer ID within your platform. Later steps show how to define these custom identifiers for your customers in Metronome.
  • event_type, an arbitrary string that you can define within the request.
  • properties, an arbitrary set of data to include within the payload for metering and grouping within Metronome.
Success with Metronome depends on the data you provide, so its important to design usage events well. To view all events sent to Metronome, go to the Events tab in the Metronome app. For the event sent in the example, it successfully made it into the Metronome system. But, it hasnt been matched yet with a metric to start metering or a customer in the system.

3. Create a billable metric

A billable metric describes a per-customer aggregation over a subset of usage events. By configuring a billable metric, you instruct Metronome how to match usage events to products you charge for. Heres an example billable metric configuration that matches against the usage event sent in the previous example:
The properties used in the code include:
  • name, the name to give your billable metric.
  • event_type_filter, the set of values that matched against the event_type field in the usage events. Omit this if you want to match against all event types.
  • property_filters, the set of properties you expect to find on the usage payload. If you mark a property as exists=True in the billable metric definition and the property not found on the payload, the billable metric wont match to the event.
  • aggregation_key, used to define the property with the relevant value to aggregate on.
  • aggregation_type, used to tell Metronome how to aggregate the values specified by the aggregation_key as they come into the system. Supported operations are SUM, COUNT, and MAX.
  • group_keys, used to define properties to separate the usage data into different buckets, similar to a group by clause in SQL. The example above set user_id as a group key, so you can display the invoice separated by the amount of tokens that each user consumed.
Note that billable metrics only match usage events sent after the billable metric is created. Now that you created the metric, send in another usage event to ensure that it matches as expected:
The new usage event matches the defined billable metric.

4. Create a customer

Usage events impact billing for customers, so the next step is to create a customer in Metronome. Use the SDK to create a customer, similar to this example:
The properties used in this example include:
  • name, the display name for the customer in Metronome.
  • ingest_aliases, a list of identifiers used to match a Metronome customer against a usage event. Ingest aliases are useful if you want to start flowing in usage for customers before theyre created in Metronome. To do this, use the ID from your applications customer table.
In the example, you associated the newly created customer with the ingest alias team@example.com, so the previous event gets matched correctly. After you set the customer up for invoicing in the next section, this event contributes to their current invoice.

5. Set up pricing and packaging

Next, set up prices and packaging, defined using products and rate cards. In the example, you want to charge your customer based on their usage of langModel4 at a rate of $0.50 per 1 million tokens. The first step is to create a product for your billable metric. A product is where you configure the billable metric for presentation on the eventual invoice. Its also where you can associate the metric with items in external systems, like the Stripe customer ID. Learn about the configuration options for products in the API docs for the create product endpoint. Create a product associated to the billable metric, similar to this example:
The properties used in this example include:
  • name, the name of the product that appears on the invoice. Often a cleaned presentation of the billable metric name (Language Model 4 Tokens (millions) versus langModel4).
  • type, determines how a product gets charged. Supported types include usage, fixed, composite (for percentages of other usage products), and subscription.
  • billable_metric_id, associates the product presentation with an existing billable metric.
  • presentation_group_key, used to group line items on your invoice by a given property value.
  • quantity_conversion, used to multiply or divide quantities displayed on the final invoice. For example, charge by million tokens (mTok) while sending in usage at the individual token level.
Next, attach a price for the product by adding rates to a rate card. Build a rate card for your new product, similar to this example:
The properties used in this example include:
  • entitled, a boolean that indicates whether a rate shows up by default on a customers invoice. If False, it wont appear on a customers invoice unless overridden at the contract level.
  • rate_type, used to configure how a rate gets applied as usage flows in. Supported values include FLAT or TIERED.
  • price, the rate itself. For USD, values are in cents (for example, 100 = $1.00). Other currencies use whole units. See currency denomination for details.
  • starting_at, used to set the time when the rate goes into effect. To evolve your rates over time, set starting_at and ending_before dates to ensure smooth pricing updates.
You can use this rate card for all SKUs across your product catalog.

6. Create a contract

To start generating invoices for a customer, put them on a contract. A contract is an object that represents the terms a customer has agreed to pay, generally based on your rate card. At its most simple, a customer can have a basic contract where they pay the predefined list prices; this may cover many of your simple self-serve cases. If you have specific discounts or commits that a customer negotiated, configure these in the contract on top of the base list prices. Add your created customer to a contract, similar to this example that uses the Language Model List Pricing rate card:
After creating the contract, invoices get generated for all billing periods that occurred after the starting_at date. Usage data from the current period is visible to the DRAFT invoice. Line items on draft invoices update seconds after Metronome receives usage data. For the new contract from the example, the previously sent usage of 1 million tokens got applied. Next, send in a few more usage events and see it update in real time:
After refreshing the invoice, the values from the three event payloads above applies to the running line item totals. The group keys previously applied let you separate out the invoice presentation by the user ID associated with the usage.
API quickstart
Previous
Manage contracts in Stripe
Next

Web Proxy Viewer  |  New URL  |  Original Page