Set prepaid balance thresholds

Use prepaid balance threshold billing to enable a prepaid credit model for your products. This billing model requires customers to pay for usage ahead of using the product and to maintain a positive balance to continue accessing the product. Prepaid credits are modeled as commits in Metronome.

Prepaid balance thresholds enable:

• Auto recharge: Automatically recharge a customer's balance when it drops to the threshold_amount
• Manual purchase: Manually purchase commits for customers who don't want to enable auto recharge
• Payment gating: Gate the release of the commit balance, from an auto recharge or a manual purchase, based on successful collection of payment

info

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

Set up auto recharge with balance thresholds

Configuring auto recharge of the customer's balance on a contract ensures they never lose access to the product.

Create a contract with balance thresholds

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

• The threshold_amount for the customer's contract: the balance level when a customer is recharged.

• The recharge_to_amount: the balance the customer is topped up to after a recharge initiates.

• A payment_gate_config: configure whether to gate the release of balance on payment and what gateway to use.

  • Select EXTERNAL if you use a gateway that Metronome doesn't currently support.
  • 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.

• If the config is_enabled. If a payment fails and payment gating is enabled, this shifts to false.

Configure billing

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

Create contracts with prepaid balance thresholds in the Metronome app or using the Metronome API.

{
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",
    "rate_card_id": "a7bc3775-b651-46b6-b7e4-d225a7e55c4c",
    "starting_at": "2025-05-01T00:00:00.000Z",
    "billing_provider_configuration": {
        "billing_provider_configuration_id": "0d40d6ef-6a79-45c2-a716-13eed27a9c8d"
    },
    "prepaid_balance_threshold_configuration": {
        "commit": {
            "product_id": "d6be3bf4-1669-40c9-a8b1-388bb167ab16",
            "name": "prepaid_commit",
            "description": "hello_its_me_im_in_california_dreaming"
        },
        "is_enabled": true,
        "payment_gate_config": {
            "payment_gate_type": "STRIPE",
            "stripe_config": {
                "payment_type": "PAYMENT_INTENT"
            }
        },
        "threshold_amount": 500,
        "recharge_to_amount": 2100
    }
}

Update the contract's prepaid balance threshold

Update or add a prepaid_balance_threshold_configuration by editing the contract. For example, you can update the threshold_amount on a contract.

Note that these changes take effect immediately and Metronome will force an evaluation of the customer's current balance on config change.

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

{
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",
    "contract_id": "e066a32a-3b59-4d07-a91f-a9e084903d45",
    "update_prepaid_balance_threshold_configuration": {
        "threshold_amount": 600,
        "recharge_to_amount": 2700
    }
}

Prepaid balance threshold billing lifecycle

To best utilize prepaid balance threshold billing, consider its lifecycle: the actions Metronome takes and what actions you may need to take.

1. Charge for prepaid balance threshold amount (Metronome)

Once configured, Metronome evaluates the remaining balance available to the customer on the contract to determine when the threshold_amount has been reached. If the payment_gate_config is set to Stripe, Metronome attempts to charge the customer in Stripe.

If payment is successful, Metronome creates a commit for the amount that recharges the customer back to the recharge_to_amount.

2. Manage notifications (you)

Metronome fires three types of webhook notifications for prepaid balance threshold billing:

• payment_gate.threshold_reached when the customer hits their threshold.
• payment_gate.payment_status after payment has been attempted. The status of that payment, paid or failed, is denoted in the payment_status field.
• payment_gate.payment_pending_action_required if intervention is required to process payment.

Your webhook endpoint must be configured to handle these notifications accordingly.

3. Handle failed payments (you)

If a payment fails, you receive a payment_gate.payment_status with the value of failed. Additionally, the contract's is_enabled field is set to false.

You should expect to see a voided invoice in Metronome and Stripe for this transaction.

At this point, you should follow up with your customer directly or by creating an automated workflow triggered by this webhook notification.

Once you're ready to reattempt payment, set the contract's is_enabled field to true. This forces the contract to evaluate against the threshold_amount, resulting in a new payment attempt.

No automatic retries

Metronome does not automatically retry failed payments (as any automatic retries would likely fail, too).

Use an 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 prepaid balance threshold config with payment_gate_type set to EXTERNAL.
• Listen for payment_gate.external_initiate that indicates Metronome is ready to receive the outcome of the payment.
• Save the workflow_id - you 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.