Skip to main content

Provision a customer

In Metronome, customers are the recipients of an invoice and may represent individual users, enterprises, API keys, or whatever specification your organization needs. This guide describes how to provision a customer in Metronome.

Provisioning your customer includes creating the customer object and configuring the associated contract that outlines their terms of use. A customer needs at least one contract provisioned to them to start metering and rating for billing. You can also configure multiple contracts per customer, if needed.

info

To invoice a customer through a Metronome billing integration, follow the steps in Invoice with Stripe or Invoice with the Marketplaces (AWS and Azure).

Prerequisites​

Before provisioning a customer you must have:

Create a customer​

Create an individual customer object in Metronome or build a flow to create customers programmatically from system triggers.

Understand ingest aliases​

Ingest aliases map your internal customer identifiers to Metronome’s customer ID. When you send usage keyed on an ingest alias, Metronome automatically associates it to the correct Metronome customer. This allows you to maintain your existing customer entities without needing to swap in a Metronome customer ID.

Ingest aliases can also be used to maintain account hierarchy. Enterprise customers often have sub-organizations that roll up to a single contract. Use ingest aliases to model this. For example, you can represent the enterprise organization as a customer in Metronome, with each sub-organization represented by an ingest alias attached to that customer:

Parent Account - Metronome Customer e7f893e5-07f7-483b-8c16-6905944c6a89
  + Sub-Org 1 - IngestAlias1
  + Sub-Org 2 - IngestAlias2
  + Sub-Org 3 - IngestAlias3
  + Sub-Org 4 - IngestAlias4

You can split out each sub-organization’s usage on the invoice Metronome generates. Learn how to use group keys to modify invoice presentation.

Ingest aliases can be specified on the Metronome customer object at time of creation or any point after. Retroactively adding an ingest alias on the customer is a way to take Metronome out of the hot path of customer signup while properly metering usage. For example, if you first send usage keyed on IngestAlias1 and later add this ingest alias to an existing customer, Metronome retroactively associates that usage to the correct customer.

Create a customer with the Metronome app​

To create a customer using the app:

  1. Go to the Customers page → Add a customer.
  2. Add a name.
  3. Add an ingest alias.
  4. (Optional) Set a custom field for the customer on the Settings tab.

Build a customer creation flow with the API​

Use the Metronome API to build a flow for creating customers in Metronome programmatically based on sales-led or product-led motions.

For a sales-led motion, you might use Salesforce CPQ to capture opportunities. When an opportunity closes, you can schedule a job to create a customer using the Metronome API.

This example request shows how to:

  • Create a mock customer, WidgetsExpress, in Metronome
  • Codify the relationship between the Metronome customer and the SFDC account by storing the sfdc_account_id in a custom field
curl https://api.metronome.com/v1/customers \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_aliases": [
      "team@widgetsexpress.com"
    ],
    "name": "WidgetsExpress",
    "custom_fields": {
      "sfdc_account_id": "sfdc1001"
    }
  }'

For a product-led growth motion, create a similar workflow where the trigger originates from a signup on your website. Store the relationship between the Metronome customer and your internal customer object.

Provision a customer contract​

Define a contract in Metronome that encodes the products customers can access, rates for each product, and access duration. Just as rate cards are built on products, contracts are built on rate cards. A contract references a specific rate card and bundles it with other Metronome models like commits, discounts, fixed products that don’t live on the rate card, and more.

Create contracts with the Metronome app or with the /contracts/create endpoint.

Create a contract​

Consider an example where your customer, WidgetsExpress, purchased a prepaid commit for $10,000 that applies to your cloud products. This commit lasts for a year. As part of the contract, they also pay a $1,000 platform fee each quarter to use your service. They pay for the prepaid commit once upfront and for usage on a monthly basis.

To provision this contract with the Metronome app:

  1. Navigate to Customers and select your newly created customer.
  2. Under Provision Customer on the Overview tab, select + Add -> Contract.
  3. Enter in the desired contract metadata (name, start date, and usage statement cadence).
  4. Add the prepaid commit by clicking and following the instructions from Add a commit.
  5. Click Add a term to add the platform fee as a scheduled charge.

The final contract looks like:

Final contract

To create the example contract with the /contracts/create API, execute this call:

curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "aa58107d-162f-407e-9f09-940f16adbb1c",
    "rate_card_alias": "base_usage_products",
    "starting_at": "2024-11-01T00:00:00.000Z",
    "commits": [
      {
        "type": "prepaid",
        "name": "Contract Prepaid Commit",
        "product_id": "a1f4e40b-f8c4-496b-b687-0a103396b479",
        "access_schedule": {
          "schedule_items": [
            {
              "amount": 1000000,
              "starting_at": "2024-11-01T00:00:00.000Z",
              "ending_before": "2025-11-01T00:00:00.000Z"
            }
          ]
        },
        "invoice_schedule": {
          "schedule_items": [
            {
              "unit_price": 1000000,
              "quantity": 1,
              "timestamp": "2024-11-01T00:00:00.000Z"
            }
          ]
        },
        "applicable_product_tags": ["cloud"],
        "description": "Usage Commit"
      }
    ],
    "scheduled_charges": [
      {
        "product_id": "06cf3703-3f5e-467c-8ba1-0ee934c740b9",
        "name": "Platform Charge",
        "schedule": {
          "recurring_schedule": {
            "starting_at": "2024-11-01T00:00:00.000Z",
            "ending_before": "2025-11-01T00:00:00.000Z",
            "frequency": "quarterly",
            "unit_price": 100000,
            "quantity": 1,
            "amount_distribution": "each"
          }
        }
      }
    ],
    "usage_statement_schedule": {
      "frequency": "monthly",
      "day": "contract_start"
    }
  }'

Add contract discounts and overrides​

Provide discounts during contract creation or on an existing contract with a contract amendment.

Apply discounts with credits, overrides for product rates, price tiers, and more. If you use dimensional pricing, set price overrides for each combination of group key and product. To add additional terms like credits, commits, overrides for product rates, and more, create a contract amendment.

Consider the example with your mock customer WidgetsExpress to see this in practice. The customer negotiated a discount on cloud products. To address this, add an amendment that overrides products with the cloud tag to be 5% off of the basic rate card.

To add an amendment with the Metronome app, go to the WidgetsExpress customer → Contracts -> and select the contract that you would like to ammend. Click the overflow button in the top right → click Add an amendment.

To add an amendment through the API, execute this call:

curl https://api.metronome.com/v1/contracts/amend \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "aa58107d-162f-407e-9f09-940f16adbb1c",
    "contract_id": "0a6180da-336a-40e6-98f4-20b6be08211d",
    "starting_at": "2024-11-01T00:00:00.000Z",
    "overrides": [
      {
        "starting_at": "2024-11-01T00:00:00.000Z",
        "entitled": true,
        "type": "multiplier",
        "multiplier": 0.95,
        "applicable_product_tags": ["cloud"]
      }
    ]
  }'

Create a usage filter​

You can provision a customer with multiple contracts simultaneously. These contracts can use distinct rate cards, have different start and end dates, discounts, and more. They can all draw down from shared customer-level commits and credits. To specify that usage should count against one contract instead of another, create a usage filter for that contract.

For example, your mock customer WidgetsExpress has three sub-divisions: US, EU, and APAC. Each division negotiated different discounts. To model this in Metronome, create a contract for each sub-division and use usage filters to ensure only the appropriate usage gets routed to each contract.

When creating the US contract, ensure that only events with the property region and value US are included in this contract using this API call:

curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
    "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "starting_at": "2024-10-01T00:00:00.000Z",
    "usage_filter": {
      "group_key": "region",
      "group_values": [
        "US"
      ]
    }
  }'

You can update the usage filter on a contract at any time, on a schedule. For example, imagine that as of 2025, WidgetsExpress no longer wants usage within their EU division invoiced separately. Instead, they should get billed through the US contract, using US prices.

This API call shows how to update the usage filter, with the edit taking effect on Jan 01, 2025:

curl https://api.metronome.com/v1/contracts/setUsageFilter \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
    "contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "group_key": "region",
    "group_values": ["US", "EU"],
    "starting_at": "2025-01-01T00:00:00.000Z"
  }'

Usage filters have these limitations:

  • For streaming billable metrics, you must define the usage filter as a group key on the underlying billable metric. If you’re also using dimensional pricing and presentation group keys, the usage filter group key must be defined in a compound group key on the underlying billable metric with the dimensional pricing and presentation group keys.
  • For SQL billable metrics, the group key for the usage filter must be present as property value in the underlying events (for example, properties.region).

Add custom fields​

Use custom fields to add additional metadata to the contract or commit. This metadata can power downstream processes like revenue recognition workflows.

For example, if you’re integrating with SFDC, you can create a custom field for salesforce_opportunity_id to map Metronome contracts, and revenue derived from it, to the associated SFDC opportunity.

© 2024 Metronome. All rights reserved.
CareersBlogLog in