Prepaid Account Balance

Have subscribers prepay for their future purchases and collect cash immediately. You can now drive higher acquisition and conversion rates by offering discounts to your customers if they make a prepayment.


Allows customers to pay in advance and have money added to an account balance which can be used to pay for future subscription and one time purchase invoices. Specifically, a customer can make a purchase that is immediately reflected in the customer’s account balance. Then as the customer is invoiced, the customer’s prepaid balance is automatically deducted by the invoiced amount. This way, merchants can collect payments upfront instead of at the time of invoice.

With Prepaid Account Balance, merchants can reduce transaction costs significantly. There are no transaction fees or interchange charges when a subscriber is using the account balance. Have your subscribers add to their prepaid account balance for subscriptions that have multiple billing periods in a term or for micro-transactions.

How to create a Prepaid Account Balance

Prepaid Account Balance can be updated in API V2, API V3, or the Admin Console.

  • For the V3 API, create a Purchase request for a line_item with an "origin" = "prepayment" .
  • For the V2 API, create a Purchase for a charge adjustment with an "origin" = "prepayment".
  • For the Recurly Admin Console, create a charge with a timeframe of immediately. Select Prepaid Account Balance and provide an amount. You can preview the charge before it is created.

When the purchase request is successful, the amount of the transaction will be added to the Account Balance. All future subscriptions and one time purchases will pull from the account balance until it reaches zero. When the account balance reaches zero, the card on file will be billed for future transactions. If the purchase transaction fails, the invoice will be marked as failed and will collection will be attempted by dunning.


The Hosted Account Management page will display the account balance, active subscriptions and all associated invoices to provide clarity for subscribers.

A few things to note about Prepaid Account Balances

  • Must be tax-exempt. Taxes should be charged if needed when the actual product/service is sold.
  • Purchase requests to add to the prepaid account balance should not be combined with other line items in the request.
  • Purchase requests for the prepaid account balance must be invoiced immediately and can't be invoiced at renewal.
  • Credits from prepaid account balance cannot pay for additional account balances. Prepaid balances will not be used towards subsequent prepaid account balance purchases.
  • Revenue Recognition for account balance will need to be managed by the merchant. Specify how you want to recognize the balance and the subsequent subscriptions/one time purchases. In order to keep your books aligned, recognize revenue on the initial purchase or the subsequent purchases but not both.
  • See Adjustments for the order of how credits and account balance are used on invoices.
  • If Account Hierarchy is enabled on your site, Credit invoices from the parent account can be used to pay for the child account
  • If an account has a prepaid balance on it, the balance can be applied to past due invoices (learn more).

Prepaid Account Balance for Manual Invoices

If the collection method is set to Manual, the account balance will be in a processing state until the manual payment is collected. Ensure you have a proper collection process to collect the manual invoices and fund the prepaid balance.

Prepaid Account Balance for Asynchronous Payment Methods

Prepayments made via the UI, as well as for ACH and other direct debit payment methods, the prepaid balance will not be funded until Recurly receives a notification of successful transaction, and the credit invoice will remain in a processing state. After the success notification, the credit invoice will move to an open state.

Additionally, if a charge back notification is received and if that balance has not been fully used, Recurly will refund the credit invoice balance to a charge back transaction and close the invoice. If there has been credit applied from the prepayment balance, then the merchant will need to decide how they want to handle the credit that was applied to the balances on those invoices.

While the prepaid balance is in a processing state, merchants can use the accounts/account_id/balance endpoints in V3 and V2 to GET any processing prepayment amount.


Prepaid account balances that haven't been utilized can be refunded. The amount will be refunded back to the original payment method. Each invoice will have an associated credit and charge invoice which can be used for the refund. If the account balance has already been utilized, the invoice will not be refundable.


  • Credit Invoices and Only Bill What Changed must be enabled to utilize the prepaid account balance.
  • Available on all Recurly plans