API quickstart

​

Prerequisites

• A Metronome sandbox account (sign up here)
• Your Metronome sandbox API token (Connections → API Tokens & webhooks in the dashboard)

​

Environments & authentication

​

Step 1: Understand how the pieces fit together

• Usage Events — Raw records of customer activity sent to Metronome (e.g., “customer X used 1,500 input tokens on model gpt-5 at timestamp Z”)
• Billable Metrics — Rules that aggregate your events into billable quantities (e.g., “sum the input_tokens property for events of type llm_request”). This is also where you define group keys — the properties you’ll use to price by or display on invoices.
• Products — Named line items on an invoice.
• Rate Cards — A centralized price book assigning a price to each product. A single rate card can be shared across many customers, making pricing updates easy to roll out.
• Contracts — Customer-specific agreements referencing a rate card, defining the billing period, and optionally including credits, commits, or overrides.
• Packages — Encodes your rate card and contract details in a single package to be applied across new customers.
• Invoices — Automatically generated each billing period based on a customer’s recurring charges and usage, rated against the contract.

1. A billable metric
2. A product
3. A rate card with rates for each product
4. A customer
5. A contract linking the customer to the rate card

​

Step 2: Design your event schema

{
  "transaction_id": "2026-03-09T14:30:00Z_req_abc123",
  "customer_id": "your-customer-uuid-in-metronome",
  "event_type": "llm_request",
  "timestamp": "2026-03-09T14:30:00Z",
  "properties": {
    "model": "gpt-5",
    "input_tokens": "1500",
    "output_tokens": "350",
    "provider": "openai",
    "region": "us-east-1",
    "user_id": "user_8f3a",
    "cost": "0.0042"
  }
}

​

Required fields

• transaction_id — Unique per event for idempotency. If the same transaction_id is sent twice, Metronome deduplicates. Tip: combine timestamp + request ID.
• customer_id — Metronome customer UUID, or an ingest_alias configured on the customer (so you can use your own internal ID).
• event_type — String connecting this event to a billable metric. Must exactly match the billable metric’s event_type_filter in_values.
• timestamp — ISO 8601 format. Must be within the last 34 days (Metronome’s backdating window). Future-dated events are rejected.

​

Properties (metric-dependent)

• properties — Key-value pairs. All values should be strings (even numbers) — Metronome uses arbitrary-precision decimals internally to avoid floating point issues. Metronome also supports up to 2,000 properties per event.

1. Aggregation — The value you sum, count, or max (e.g., input_tokens, duration_seconds)
2. Group keys — Dimensions for pricing (e.g., model, region) or invoice display (e.g., user_id, project_id). Must be defined on the billable metric first.
3. Metadata — Context for customers, COGS analysis, or future-proofing (e.g., provider, cost, endpoint)

​

Common event patterns

​

Step 3: Create a billable metric

​

Example — Count API calls (simple):

curl -X POST https://api.metronome.com/v1/billable-metrics/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "aggregation_type": "count",
    "event_type_filter": {
      "in_values": ["api_call"]
    }
  }'

​

Example — Sum tokens with group keys:

curl -X POST https://api.metronome.com/v1/billable-metrics/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Input Tokens",
    "aggregation_type": "sum",
    "aggregation_key": "input_tokens",
    "event_type_filter": {
      "in_values": ["llm_request"]
    },
    "property_filters": [
      { "name": "model", "exists": true },
      { "name": "input_tokens", "exists": true },
      { "name": "user_id", "exists": true }
    ],
    "group_keys": [["model"], ["user_id"]]
  }'

​

Aggregation types

• count — Number of matching events (API calls, requests)
• sum — Sum of a numeric property (tokens, bytes, seconds)
• max — Maximum value in a window (peak storage, concurrent connections)

​

Group keys

​

SQL billable metrics

SELECT count(DISTINCT properties.user_id) as value,
       properties.region
FROM events
WHERE event_type = 'api_request'
GROUP BY properties.region

​

Step 4: Create a product

​

Example — Usage product with group keys:

curl -X POST https://api.metronome.com/v1/contract-pricing/products/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Input Tokens",
    "type": "usage",
    "billable_metric_id": "<your-billable-metric-id>",
    "pricing_group_key": ["model"],
    "presentation_group_key": ["user_id"]
  }'

​

Product types

• usage — Variably priced based on customer usage (requires a billable metric)
• subscription — Recurring fee on a schedule (platform fees, seat licenses)
• composite — Percentage charge on a usage product
• fixed — One-time or scheduled charges (commits, credits, one-time fees)

​

Group key assignment

​

Step 5: Create a rate card

​

Create the rate card:

curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standard Pricing"}'

​

Add Rates:

curl --request POST \
  --url https://api.metronome.com/v1/contract-pricing/rate-cards/addRates \
  --header 'Authorization: Bearer $METRONOME_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "rates": [
    {
      "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "entitled": true,
      "rate_type": "FLAT",
      "price": 100,
      "pricing_group_values": {
        "region": "us-west-2",
        "cloud": "aws"
      }
    },
    {
      "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "entitled": true,
      "rate_type": "FLAT",
      "price": 120,
      "pricing_group_values": {
        "region": "us-east-2",
        "cloud": "aws"
      }
    }
  ]
}
'

​

Add dimensional pricing (one entry per value):

curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/rates/add \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_card_id": "<your-rate-card-id>",
    "product_id": "<your-product-id>",
    "starting_at": "2026-03-01T00:00:00Z",
    "rate_type": "flat",
    "price": 1.50,
    "entitled": true,
    "pricing_group_values": {
      "model": "gpt-5"
    }
  }'

​

Additional capabilities

• Tiered pricing — Volume-based tiers via the tiers field on a rate entry
• Custom Pricing Units — Create under Offering → Pricing Units in the UI, then reference the credit_type_id on the rate card for credit-based billing. Learn more →
• Commit rates — Rates that apply specifically to prepaid commit drawdown

​

Step 6: Create a customer and contract

​

Create a customer:

curl -X POST https://api.metronome.com/v1/customers/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Customer",
    "ingest_aliases": ["my-internal-customer-id"]
  }'

​

Create a contract:

curl -X POST https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<your-customer-id>",
    "rate_card_id": "<your-rate-card-id>",
    "starting_at": "2026-03-01T00:00:00Z",
    "usage_statement_schedule": {
      "frequency": "MONTHLY"
    }
  }'

"billing_provider_configuration": {
  "billing_provider": "stripe",
  "delivery_method": "direct_to_billing_provider"
}

​

Step 7: Send your first events

curl -X POST https://api.metronome.com/v1/ingest \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{
    "transaction_id": "test-001",
    "customer_id": "<your-customer-id>",
    "event_type": "llm_request",
    "timestamp": "2026-03-09T12:00:00Z",
    "properties": {
      "model": "gpt-5",
      "input_tokens": "1500",
      "user_id": "user_1"
    }
  },
  {
    "transaction_id": "test-002",
    "customer_id": "<your-customer-id>",
    "event_type": "llm_request",
    "timestamp": "2026-03-09T12:01:00Z",
    "properties": {
      "model": "gpt-5-mini",
      "input_tokens": "800",
      "user_id": "user_2"
    }
  }]'

​

Important behaviors

• A 200 response means events were accepted for ingestion. Check the response body for per-event errors.
• Note that if there’s no matching BM for the event_type or required properties are not included, events are stored but may not appear in usage calculations. Be sure to create billable metrics before sending events if they are needed for rating.
• Events can be backdated up to 34 days. Events with future timestamps are rejected.
• transaction_id is used for deduplication. Sending the same ID twice won’t double-bill.
• Only ingest endpoint events are metered. API calls for managing customers, contracts, etc. are not billable.

​

Verify your events

​

Troubleshooting

1. Click into the event on the Events page — verify it matched a BM and customer.
2. Check the API response from your ingest call for per-event errors.
3. If events match a BM + customer but don’t appear on the invoice: The pricing group key values in the event likely don’t match any rate on the rate card. For example, "model": "gpt-5" vs "model": "gpt5" (missing hyphen) will silently fail to rate.
4. Verify your API token is for sandbox (not production, or vice versa).

​

Step 8: Verify your invoice

1. Draft — Accumulates usage throughout the billing period (viewable in Metronome)
2. Finalized — Locked at end of billing period. There is a 24 hour grace period at the end of the billing period before invoices are finalized to make any necessary changes to an invoice.
3. Sent to billing provider — If Stripe is connected, pushed within ~1 hour of finalization. Payment status managed in Stripe’s dashboard.
4. Paid / Failed — Collection handled by your billing provider

​

Ready for more?

• Embeddable Customer Dashboards — Self-serve usage visibility for your customers
• Webhooks — Invoice lifecycle, balance alerts, payment events
• Alerts & Notifications — Spend thresholds, balance notifications
• Credits & Commits — Prepaid balances, enterprise commitments
• Stripe Integration — Automated payment collection
• Revenue Recognition — ASC 606 / IFRS 15
• Production Checklist — When you’re ready to go live (new API token, same base URL, live Stripe keys)