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.
INFOTo 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. On the Overview tab, click the + Add button on the right hand side of the Contracts pane.
  3. Fill in the Basic info for the contract like the contract name, start date, and rate card to use.
  4. Under Terms, click Add -> Commit and fill in the details for the prepaid commit.
  5. Under Terms, click Add -> Scheduled charges and 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"
        }
      }'

​
Consolidate usage and scheduled invoices

You have the option to specify if scheduled invoices should consolidate onto a customer’s usage invoices. This setting applies to all charges (including commits) on the contract. It follows this logic to determine whether to consolidate invoices:
  • The last day of the usage service period (exclusive) falls on the same day as the scheduled date for the scheduled invoice.
  • The corresponding usage invoice hasn’t finalized.
Consolidation occurs at the time of contract creation and upon any contract changes in the future. Consider an example where a new customer buys the Best package on your website, which costs $75 per month. As part of this package, they receive a $100 monthly commit. The contract and recurring commit start on January 1 with no end date. If scheduled_charges_on_usage_invoices is set to ALL, the contract creates these invoices:
  • Invoice 1: Issued and finalized on January 1 with one line item for the $75 monthly charge.
  • Invoice 2: Created in draft with one line item for the $75 monthly charge in February in addition to all usage charges for January.
  • Invoice X: Assuming no changes to the contract, all future invoices will model invoice 2.

​
Add contract discounts and overrides

Provide discounts during contract creation or by editing an existing contract. 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, edit the contract. Consider the example with your mock customer WidgetsExpress to see this in practice. The customer negotiated a discount on cloud products. To address this, edit the contract by overriding products with the cloud tag to be 5% off of the basic rate card. To edit a contract with the Metronome app, go to the WidgetsExpress customer → Contracts -> and select the contract that you would like to edit. To edit a contract through the API, execute this call: 
curl https://api.metronome.com/v2/contracts/edit \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "aa58107d-162f-407e-9f09-940f16adbb1c",
    "contract_id": "0a6180da-336a-40e6-98f4-20b6be08211d",
    "add_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.