Enforce spend thresholds

To reduce fraud in Product-Led Growth (PLG) workflows, Metronome supports spend threshold billing. This feature allows you to cap the amount a customer can spend before being charged, thereby limiting your exposure to uncollected revenue.

After applying a spend threshold to a contract, watch for webhook notifications to be alerted when payments succeed or fail.

info

Spend threshold billing is currently in beta. It’s available for production use, but you may encounter product limitations. Breaking changes may occur.

Create a contract with spend thresholds

When you create a contract in Metronome, you can optionally configure a spend_threshold_configuration. This config dictates:

• The threshold_amount for the customer’s contract: how much they can spend before a payment attempt is triggered
• The payment_gate_config:
  • Configure whether to payment gate the release of the commit and what gateway to use. Select EXTERNAL if you are using a gateway Metronome does not currently support. See Use an external payment gate for details.
  • If using Stripe, configure PAYMENT_TYPE to dictate whether payment is sent as an invoice through Stripe Billing or directly as a paymentIntent to Stripe's payment gateway.
  • If using Stripe, select your existing tax provider.
• What product_id should be used to represent the commit: the product_id dictates what the customer sees on their incremental invoice

Configure billing

If using Stripe as your payment gateway, ensure there is a valid Stripe billing configuration set on the contract. Additionally, set spend_threshold_configuration.is_enabled to true if you want Metronome to immediately evaluate the contract after its creation.

Create contracts with spend threshold in the Metronome app or using the Metronome API.

{
    "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
    "rate_card_id": "a7bc3775-b651-46b6-b7e4-d225a7e55c4c",
    "starting_at": "2025-04-01T00:00:00.000Z",
    "billing_provider_configuration": {
        "billing_provider_configuration_id": "211ef270-098f-422c-9ca8-7999bb9156cb"
    },
    ...
    "spend_threshold_configuration": {
        "commit": {
            "product_id": "d6be3bf4-1669-40c9-a8b1-388bb167ab16",
            "name": "black_mesa_commit",
            "description": "hello_its_me_im_in_california_dreaming"
        },
        "is_enabled": true,
        "payment_gate_config": {
            "payment_gate_type": "NONE"
        },
        "threshold_amount": 200
    }
}

Update a contract’s spend threshold

You can update or add a spend_threshold_configuration at any point by editing the user's contract. Add spend threshold limits to existing, non-limited contracts or change existing limits on a contract (for example, after some period of successful payments).

Note that these changes take effect immediately.

Edit contracts in the Metronome app or with the Metronome API. This API call adds a spend threshold to a contract:

{
    "customer_id": "52f5a554-b887-4899-b919-4eb7789c6bf3",
    "contract_id": "8a5529d3-f353-4231-bedf-7e83f5e9331d",
    "add_spend_threshold_configuration": {
        "commit": {
            "product_id": "d6be3bf4-1669-40c9-a8b1-388bb167ab16",
            "name": "threshold_charge",
            "description": "one time for the one time"
        },
        "is_enabled": true,
        "payment_gate_config": {
            "payment_gate_type": "STRIPE",
            "stripe_config": {
                "payment_type": "INVOICE"
            }
        },
        "threshold_amount": 100
    }
}

This API call updates an existing spend threshold:

{
    "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
    "contract_id": "6058587f-763c-400f-a822-3edb3eb2b86b",
    "update_spend_threshold_configuration": {
        "is_enabled": true,
        "threshold_amount": 100,
        "payment_gate_config": {
            "payment_gate_type": "STRIPE",
            "stripe_config": {
                "payment_type": "INVOICE"
            }
        }
    }
}

Manage notifications and handle failed payments

To learn how to manage webhook notifications from Metronome and handle failed customer payments, see the threshold billing lifecycle.

Using external payment gate

If using the EXTERNAL option for payment_gate_type, you are responsible for facilitating payment and letting Metronome know the response. Follow this workflow:

• Set the spend threshold config with payment_gate_type set to EXTERNAL
• Listen for payment_gate.external_initiate that indicates Metronome is ready to recieve the outcome of the payment
• Save the workflow_id - you will need this to release the commit
• Charge the customer in your payment gateway of choice
• Call commits/threshold-billing/release to either release the commit on successful payment, or cancel the commit in case of failure.