Usage based pricing with billing thresholds

Implementation time: 1 minute

Stripe offers a “billing thresholds” feature for companies that offer usage-based pricing models and want to limit the amount owed, or to limit the products consumed, between invoices for a subscription. For example, companies that charge customers at the end of the month for usage during a particular month might want to automatically generate an invoice for immediate payment (i.e. top up an account) if a customer reaches a certain amount of usage, to limit the credit risk associated with higher than expected usage of their product. Additional Stripe documentation surrounding this feature can be found here.

Loop enables companies to offer usage-based pricing models with billing thresholds to get paid in crypto by listening for the invoices that occur when billing thresholds are met, automatically processing those payments on-chain and marking the Stripe invoices as paid.

Loop does not support a threshold that is triggered more than once in the same day.

Steps to use this feature

The only step required to use this feature is within the subscription to check the box to “Bill immediately if accumulated usage fees reach” a value you specify, and when Stripe generates an invoice Loop will process the crypto payment. You can elect to restart the billing period or not restart it if the threshold is reached.

Stripe allows billing thresholds to be configured for usage amounts or dollar amounts via Stripe’s API, however the Stripe dashboard UI only supports setting thresholds based on the dollar amount owed. Loop supports both dollar based and usage based configurations.


The flow for usage based billing is similar to all other subscriptions.

1. Configure your product

You can verify your setup, after updating the subscription as noted above, by viewing the details for billing thresholds on the subscription page in the Stripe dashboard. It should look like this if the billing period is set to be reset when the threshold is met:

And it should look like this if the billing period is set to be unaffected by the threshold:

Loop will automatically pull in your products configured in Stripe. The cart will automatically display “Price Varies” in checkout for subscriptions with volume pricing or graduated pricing models (i.e. the subscriptions price is = 0). We suggest you edit the pricing metadata for the subscription in Loop to add a line that says “overage charges apply” (with whatever details you want).

The checkout will suggest the wallet balance for the default suggested allowance for subscriptions with volume pricing or graduated pricing models. However, you can override this value by setting the defaultSpendingCap parameter in the hosted checkout or the checkout widget. This allows you to set a default allowance amount that's a multiple you choose of the monthly subscription amount for your subscription.

2. Collect payment authorization

End customer provides authorization in checkout by connecting their wallet, choosing a token to pay in, and signing a transaction. No payment is taken at this time. The end customer will receive an email notification informing them that they have signed up for auto-pay for the subscription, with a link to the Customer Portal, where they can view their subscription, cancel their subscription, and manage their allowance amount.

3. Invoicing

If you take payment upfront, Stripe will generate the first bill for the subscription, Loop will ingest the invoice, charge the customer on-chain, and mark the invoice as paid. This all happens automatically. If you don't take payment upfront, Stripe automatically generates a $0.00 invoice, which is programmatically marked as paid. If you use an external system to report usage to Stripe, this process will work as-is; any method of usage reporting to Stripe is supported.

4. Provide product access

Since Loop marks invoices in Stripe as paid, you can continue to use any integrations you've built off of Stripe as the method for providing access. No need to change anything. However, if you want to provide access to your users based on a reference ID you pass to Loop or the end customer's wallet address, you can listen to Loop webhook events. The AgreementSignedUp event lets you know that a wallet provided authorization to be billed - it does not mean you have been paid yet, but it does indicate the user has set an allowance for payments. The TransferProcessed event is the payment notification and indicates funds have been sent to the receiving wallet. If there is a trial or coupon, there is no TransferProcessed event until the amount due is > 0 and the due date has passed. You can use an external reference ID field that you can pass to Loop during checkout, which is also returned in the AgreementSignedUp and TransferProcessedevents if it's set during checkout, to provide access to your system. You can alternatively use the wallet address or email provided in the Loop webhook AgreementSignedUp and TransferProcessed events to map to users in your system to provide access to your system.

5. Future invoices

As invoices are generated when the subscriber hits the threshold, Stripe will generate new invoices, which once finalized in Stripe will be processed automatically. If the customer doesn’t have enough allowance or balance for the payment to be processed, then the customer will receive a “late payment” email notification 5 minutes after the payment is due but is not processed. The customer will be directed to either increase their balance or can increase their allowance on Loop’s customer portal.

Companies can decide how strict they would like to be about late payments and use webhooks (noted above) to remove access to their product should a payment not be received.

6. Receipts

End customers will receive an email notification from Loop that the payment was processed when the payment is confirmed on-chain. The email notification will contain a link to the Customer Portal, which end customers can use if they need to increase their allowance for future payments, after a payment has been processed.

Last updated