Let customers control spend and usage

Transparency is crucial in usage-based pricing. Enabling customers to monitor and manage their usage in real time builds trust and encourages product adoption. Metronome provides the data and real-time control necessary to implement flexible and customizable billing functionality directly in your product. Using alerts, you can give your customers the power to proactively manage spend limits, commit balances, and invoice totals.

Metronome evaluates alerts as usage events are processed, triggering alarm states when a threshold is reached. The alerts are sent to your application through a preconfigured webhook, allowing you to take action as soon as the alarm state triggers as part of your entitlement management workflows. To learn more about supported alert types and alert behavior, see Create and manage alerts.

Enable custom spend limits

Spend limits provide an important safety mechanism to reassure customers that their total costs won't exceed a predefined threshold. These limits trigger notifications and prevent further service usage in the case of a hard limit.

Implement spend limits with the following workflow:

1. An end user sets limits in your application (see example UI below)
2. Using the Metronome API, your application creates a spend_threshold_reached alert for each limit with a threshold matching the values entered by the end user
3. Metronome continuously evaluates the spend for the billing period, setting the alerts to an in_alarm state once the threshold is reached
4. Metronome sends an alert notification to a webhook configured for your application that you can use to notify your customer and optionally block access to the service

The following API calls show how to set alerts in Metronome based on a spend threshold, enabling you to support your end users’ ability to set soft and hard limits. Each response returns the ID of the created alert. Save these to a table to make them easily available when a user wants to update their soft and hard spend limits.

curl https://api.metronome.com/v1/alerts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "spend_threshold_reached",
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "name": "SOFT spend threshold",
    "threshold": 5000,
    "customer_id": "75077603-26d4-45c0-a4b7-97b082ccc5f9"
  }'

 curl https://api.metronome.com/v1/alerts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "spend_threshold_reached",
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "name": "HARD spend threshold",
    "threshold": 10000,
    "customer_id": "75077603-26d4-45c0-a4b7-97b082ccc5f9"
  }'

info

The credit_type_id of 2714e483-4ff1-48e4-9e25-ac732e8f24f2 represents a credit unit of US cents. However, spend alerts are not limited to USD. You can set them in custom pricing units, which you can define on the Offering page in the Metronome app.

Process alert notifications sent through a webhook

Taking action on alerts in real time requires the use of webhooks—dedicated endpoints in your application for receiving and processing alert notifications. Configure webhooks in Metronome in under Connections - API tokens & webhooks.

When an alert triggers in Metronome, a POST request is sent to your webhook with basic information related to the alert, including the alert type, customer ID, and alert ID. Upon receiving a webhook notification, your application can process it and take the appropriate action. Learn more best practices around handling webhook notifications.

For the spend limit example above, processing the webhook payload might look like this:

1. Check that the alert ID matches an alert you have configured and that the customer ID matches the one you associated with the alert ID.

2. Using information included in the webhook like alert ID, alert name, and alert threshold, determine whether the customer exceeded their soft limit, or their hard limit.

3. If the customer exceeded their soft limit, notify the customer inside the app, through email, or via your preferred delivery mechanism.

4. If the customer exceeded their hard limit, disable the customer’s access to your services to prevent any additional spend. Inform the customer they have reached their hard spend limit and prompt them to update their limits in your application if they’d like to continue using the service.

5. For any limits that have changed, archive the previous alerts before creating new alerts with the updated thresholds:

   curl https://api.metronome.com/v1/alerts/archive \
     -H "Authorization: Bearer <TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "e9c0d89d-040e-4ffc-91f6-001c6954d7a7"
     }'

In addition to using webhook notifications, you can regularly check the status of customer alerts at any time that makes sense in the customer workflow, such as upon initial login. Do this with calls to the /customer-alerts/get endpoint for a specific alert, or the /customer-alerts/list endpoint for all alerts.

Enable custom spend limits for a specific dimension

Your customers may want the flexibility to set up custom spend limits for a subset of usage. For example, they may want to receive a notification or limit access once a specific user_id has spent more than $500 in a billing period, or when a specific organization_id has spent more than $5000.

In Metronome, you have the option of adding group_values filters to spend alerts to support this use case. Create an alert on spend for organization_id = finance using the following API call:

curl https://api.metronome.com/v1/alerts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "spend_threshold_reached",
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "name": "$100 spend limit for finance org",
    "threshold": 10000,
    "customer_id": "5cceec38-51fe-4399-8bed-fcb2a8ad1fb7",
    "group_values":[{"key":"organization_id", "value":"finance"}]
  }'

In order to use a key in the group_values field, make sure that key is added as a group key on billable metrics associated with that customer's contract. Spend on products where the key is not a group key on the underlying billable metrics will not contribute to the threshold.

When evaluating spend threshold alerts for a specific dimension, Metronome recomputes the invoice as if the group key is a presentation group key. In cases with tiered pricing, quantity rounding, or MAX billable metrics, the pricing and packaging will be applied to the subset of usage you define. For example, if you create an alert for organization_id = finance, the quantity will be rounded for the subset of usage by the finance org.

info

For a given customer, you can set spend alerts for three keys. For example, you can set spend alerts for a user_id, a project_id, and an organization_id, but will be prevented from adding an alert using a fourth key. Spend alerts for a specific dimension are not recommended when the key has more than 5000 values for a given customer.

Monitor commit balance

Another useful scenario for flexible alert management is helping customers monitor the balance related to a contractually established spend commit. This example assumes you have set up products, rates, contracts, and commits in Metronome and want to allow a customer to specify a commitment balance at which they want to receive a notification. See the following call below:

curl https://api.metronome.com/v1/alerts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "low_remaining_commit_balance_reached",
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "name": "Commitment Balance Alert",
    "threshold": 500,
    "customer_id": "5cceec38-51fe-4399-8bed-fcb2a8ad1fb7"
  }'

This alert gives you an opportunity to notify your customer that they’re reaching the end of their commit, or even send a message to your sales team to contact this customer for a potential renegotiation. It also provides a trigger for cutting off access if appropriate when the commit balance reaches zero.

Enable custom invoice total limits

The spend threshold reached alert described above uses a customer's usage-based spend prior to credit and commit drawdown. You can also set alerts on invoice total. The invoice total is evaluated after credit and commit drawdown and corresponds to the amount a customer will pay. To allow a customer to specify an invoice total reached alert on usage invoices, see the following call:

curl https://api.metronome.com/v1/alerts/create \
  -H "Authorization: Bearer bb842ce6470ef5fc9982b861b53c0b7c3c111ac34b7980b38b70c095e77de2c4" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "invoice_total_reached",
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "name": "$100 usage invoice total reached alert",
    "threshold": 10000,
    "customer_id": "5cceec38-51fe-4399-8bed-fcb2a8ad1fb7",
    "invoice_types_filter": ["USAGE"]
  }'