Is there a way to record advanced payments for subscriptions?

This is a great question, Yes we do We now have the option of Prepayments available via V2 and V3 of the API. 

This 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 prepayment 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.

How to setup Prepayments

Prepayments can be completed in both the V2 and V3 Recurly APIs.

  • 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 Prepayment and provide an amount. You can preview the charge before creating the prepayment.
  • 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 Prepayments:

    • Prepayments must be tax-exempt. Taxes should be charged if needed when the actual product/service is sold.
    • Prepayments purchase requests should not be combined with other line items in the request.
    • Prepayments purchase requests must be invoiced immediately and can't be invoiced at renewal.
    • Prepayments cannot pay for themselves. Account balances from prepayments will not be used towards subsequent prepayment purchases.
    • Account balances from credits on an account will be used towards the prepayment amount. If an account has $10 of credit and makes a $100 prepayment, only $90 will be charged to the payment method used for the transaction.
    • Revenue Recognition for prepayments will need to be managed by the merchant. Specify how you want to recognize the prepayment and the subsequent subscriptions/one time purchases. In order to keep your books aligned, recognize revenue on the prepayment or the subsequent purchases but not both.
    • See Adjustments for the order of how credits and prepayments are used on invoices.
    • Credit Invoices and Only Bill What Changed must be enabled to utilize Prepayments.
    • If Account Hierarchy is enabled on your site, Prepayment Credit invoices from the parent account can be used to pay for the child account

    Prepayments for Manual Invoices

    If the collection method is set to Manual for a Prepayment, the account balance will be updated immediately with the prepayment amount. If an ACH, direct debit, or other payment method is used that doesn't receive an immediate response, the credit invoice is available before the charge invoice is paid. Ensure you have a proper collection process to collect the manual invoices for prepayments.



    Prepayments 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 prepayment has already been utilized, the invoice will not be refundable.