The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Prepayments

Have subscribers prepay for their future purchases and collect cash immediately. Provides additional flexibility to have customer pay upfront and receive a discount

Overview

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.

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 prepayment purchase transaction fails, the invoice will be marked as failed and will not be collected by dunning.

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

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.

Refunds

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.

Updated about a month ago

Prepayments


Have subscribers prepay for their future purchases and collect cash immediately. Provides additional flexibility to have customer pay upfront and receive a discount

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.