Skip to main content
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 work with both fiat currencies (such as USD) and custom pricing units (such as tokens or credits). This means you can configure auto recharge for customers whose balances are denominated in custom pricing units, not just fiat currency. 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

​
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.
    • Note: When evaluating whether the threshold_amount has been reached, Metronome considers the total balance of all contract- and customer-level commits and credits. Individual seat-scoped credits are not included in this calculation.
  • 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 BILLINGIf 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  
    }  
}
RECHARGE MINIMUMSWhen setting up Auto Recharge, the recharge_threshold has a minimum value of $5, and the recharge_to amount must always be at least $10 higher than your threshold. For example, if your threshold is $10, your recharge_to_amount must be at least $20.These minimums apply regardless of whether the balance is denominated in fiat currency or a custom pricing unit. When using custom pricing units, the threshold and recharge amounts are evaluated in the custom pricing unit and converted to fiat currency using the conversion rate defined on the customer’s rate card.

​
Auto recharge with custom pricing units

Prepaid balance thresholds support custom pricing units in addition to fiat currencies. When a customer’s contract uses a custom pricing unit (such as tokens or AI credits), the threshold_amount and recharge_to_amount are expressed in that custom pricing unit. Metronome converts the recharge amount to fiat currency using the conversion rate defined on the rate card when processing payment. For example, consider an AI platform that prices usage in a custom pricing unit called “AI Tokens,” where 1 AI Token = $0.10 USD:
  • The customer’s contract has a prepaid balance of 500 AI Tokens
  • You set a threshold_amount of 50 AI Tokens and a recharge_to_amount of 500 AI Tokens
  • When the customer’s balance drops to 50 AI Tokens, Metronome initiates an auto recharge
  • Metronome creates a commit for 450 AI Tokens (the difference to reach 500) and charges the customer $45.00 USD (450 × $0.10) through the configured payment gateway
The conversion rate defined on the rate card determines how the custom pricing unit amount maps to the fiat currency charge. To learn how to set up custom pricing units and configure conversion rates on a rate card, see Set currencies and custom pricing units.

​
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 forces an evaluation of the customer’s current balance on each 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 RetriesMetronome 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:
  1. Set the prepaid balance threshold config with payment_gate_type set to EXTERNAL.
  2. Listen for payment_gate.external_initiate that indicates Metronome is ready to receive the outcome of the payment.
  3. Save the workflow_id - you need this to release the commit.
  4. Charge the customer in your payment gateway of choice.
  5. Call commits/threshold-billing/release to either release the commit on successful payment, or cancel the commit in case of failure.