Add-on: Automated recurring prepayments

Use the Automated Recurring Prepayments Add-on to offer tenants a discounted commitment period at booking and to renew their prepaid billing cycle automatically, with no manual intervention at the end of each period.The Add-on does three things: it adds a commitment period dropdown to the customer portal booking flow, it applies the matching promo code and writes the prepayment details to the rental at move-in, and it runs a daily job that generates the next prepayment invoice before the current prepaid period ends.

Before you start

Make sure:
  • The Automated recurring prepayments Add-on is installed at the business level. One installation covers every site on the account.
  • Anniversary billing is supported on monthly and 4-weekly cycles. Date of month is supported regardless of billing settings.
  • You have decided which commitment periods you want to offer (for example 3, 6 and 12 months) and what discount applies to each.

How the Add-on works

  1. A tenant selects a commitment period from a dropdown in the customer portal booking flow.
  2. The Add-on looks up the promo code mapped to that period and applies it to the move-in order. The tenant does not type a promo code.
  3. At move-in, the Add-on writes Auto prepayment period (autoPrepayments_period        ), Auto prepayment promo code (autoPrepayments_discountCode        ) and Auto prepayment next invoice date (autoPrepayments_billedUntil        ) to the unit rental.
  4. A daily job runs at 3am and checks every active rental. When a rental's prepaid period is about to end, it generates the next prepayment invoice for the same period with the same promo code applied, and advances Auto prepayment next invoice date.
  5. This repeats indefinitely until the tenant moves out or the fields are cleared.

Step 1: Create your promo codes

Create one promo code per commitment period in Main settings → Promotions.

Important: You must set both a start month and an end month on every prepayment promo code, and the end month must match the commitment period. A 3-month promo code needs a start month of 1         and an end month of 3        . A 6-month promo code needs a start month of 1     and an end month of 6    .

> > If you leave the end month blank, the promo code stays attached to the unit rental's charges indefinitely. The daily renewal job carries those existing charges forward, so the discount is applied a second time and the tenant is over-discounted on every subsequently generated prepayment invoice. Setting the end month is what stops this.

  1. Go to Main settings → Promotions
  2. Click Add promotion
  3. Enter the promo code string (for example 5off        ) and the discount value
  4. Set Start month to 1        
  5. Set End month to the number of months in the commitment period — 3    for a 3-month period, 6     for a 6-month period, 12    for a 12-month period
  6. Leave the promotion's expiry date empty
  7. Click Save
Repeat for each commitment period you plan to offer.Note: We recommend leaving the expiry date empty. The Add-on will detect an expired or deleted promo code at renewal and raise a task, but a promo code with no expiry avoids the need for manual intervention. The start and end month settings are separate from the expiry date and are always required.

Step 2: Set up the commitment period dropdown

The commitment periods a tenant sees in the booking flow come from a user custom field.
  1. Go to Settings → Custom fields
  2. Find Commitment periods (autoPrepayment_commitmentPeriod    ) under User custom fields. The Add-on creates this field for you when it is installed
  3. Add one option per commitment period you want to offer, for example:
  • 3 months (5% off)        
  • 6 months (10% off)        
  • 12 months (15% off)        
  1. Click Save

Important: Each option label must begin with the number of months. The Add-on reads the commitment period by taking the leading number from the label the tenant selected, so 3 months (5% off)   and 3-months    both work, but Three months    does not.

The discount percentages in the labels are display text only. The actual discount comes from the promo code you created in step 1.The tenant's selection is held on their user record only until the move-in starts. The Add-on reads it, applies it to the move-in order, and immediately clears it, so it does not carry over to a later booking. It is cleared again at move-out.

Step 3: Configure the Add-on settings

  1. Go to Main settings → Add-ons → Automated Recurring Prepayments → Settings
  2. SetCommitment period: Promo codeusing the key/value editor:
    • Key — the commitment period in months, numeric value only (e.g. 3    , 6    , 9    , 12    ). This must match the number at the start of the option you added to the Commitment periods field in step 2.
    • Value — the promo code string exactly as it appears in Main settings → Promotions (e.g. 10off    ). Do not enter the promo's title or description — the Add-on looks up promo codes by this string, not by title.
  3. The order you enter these in does not matter. The Add-on resolves each rental by matching its commitment period to the key, not by position.
Commitment period (months)Promo code
35off
610off
1215off
  1. Set Invoice state — enter draft     to hold renewal invoices for operator review, or sent     to send them automatically.
  2. Click Save

Note: Invoice state applies to renewal invoices only. The move-in invoice always follows your main invoicing settings.

If you are using an older version of the Add-on that only uses the string type for the custom fields, then this is how you do it:Promo codes (autoPrepayments_promocodes  ) is a plain text field, so you'll type the JSON directly as a string rather than filling in a key/value table:{ "3": "5off", "6": "10off", "12": "15off" }  Because this is a plain text field, the JSON must be typed exactly right, or the Add-on won't be able to read it. Use double quotes around every key and value — { "3": "5off" }  , not { '3': '5off' } or { 3: 5off } — and don't add a trailing comma after the last entry. A single missing quote or an extra comma is the most common cause of the "promo code configuration is invalid" task at move-in (see Troubleshooting).A quick check before saving: paste the JSON into any online JSON validator, or just count that every {   has a matching }   and every opening "   has a matching closing "  .

Invoice generation timing

The daily job runs at 3am. Regular invoices generate at 10pm the same night, so the prepayment credit always lands in the tenant's account before the regular invoice is raised against it.Anniversary billing — the renewal prepayment invoice generates on the rental's invoice generation date, which is Auto prepayment next invoice date minus the site's Nb. days to create ahead setting. No offset is applied.Date-of-month billing — the renewal prepayment invoice generates only on the site's configured Invoice creation date. If today does not match that date exactly, the Add-on skips the rental entirely, leaves Auto prepayment next invoice date unchanged, and raises no task.The job reads the date from the running job rather than the system clock, so a delayed or replayed job processes the date it was scheduled for, not today's date.If you generate a prepayment invoice manually before the daily job runs, Auto prepayment next invoice date advances by that period and the next renewal is scheduled from the new date. No duplicate invoice is created.

What happens at move-out

When a tenant moves out, the Add-on clears Auto prepayment period (autoPrepayments_period        ), Auto prepayment promo code (autoPrepayments_discountCode    ) and Auto prepayment next invoice date (autoPrepayments_billedUntil        ) from the unit rental. No further renewal invoices are generated for that rental.

Troubleshooting

The discount has been applied twice on a renewal invoice

The promo code does not have an end month set, so it remains on the unit rental's charges and is applied again when the renewal invoice is generated.

  1. Go to Main settings → Promotions and open the promo code
  2. Set Start month to 1 and End month to the number of months in the commitment period
  3. Click Save
  4. Credit and reissue any affected invoices
A renewal invoice was created with no discount, and a task was raised on the rental

The promo code stored in Auto prepayment promo code (autoPrepayments_discountCode) is no longer valid — it has expired, has not started yet, has been deleted, or is restricted to a site or unit type that does not match the rental. The Add-on still creates the renewal invoice, but without the discount, and it clears the stored promo code so the same task is not raised every cycle.

The invoice is created in whatever state your Invoice state setting specifies, so if that is set to sent the invoice will already have gone out at the undiscounted amount. Check this before doing anything else.

  1. Recreate or correct the promo code in Main settings → Promotions
  2. Set Auto prepayment promo code (autoPrepayments_discountCode) on the rental back to the promo code string
  3. Credit and reissue the invoice if it has already been sent, or apply the discount to the draft before sending
A task was raised at move-in saying the promo code should be reviewed

The promo code mapped to the tenant's commitment period either does not exist in Main settings → Promotions, or is not valid for this booking. A promo code is treated as invalid if it has expired, has not started yet, or is restricted to a site or unit type that does not match the rental. Check the code exists, is active, and that any site or unit type restrictions on it cover the unit being booked.

No renewal invoice was generated for a rental

Check, in order:

  1. Auto prepayment period (autoPrepayments_period) and Auto prepayment promo code (autoPrepayments_discountCode) are populated on the rental. The job skips rentals where these are empty.
  2. The rental has not been moved out. Move-out clears all three fields.
  3. On Date-of-month billing, today matches the site's configured Invoice creation date. The job skips every other day.
  4. Auto prepayment next invoice date has not already advanced. The job will not generate a second invoice for a period that is already covered.
A tenant wants to change their commitment period after completing the booking flow

Once the booking flow is complete, the commitment period and promo code are locked to the move-in job. The facility must cancel the move-in order in the management portal before the tenant can rebook on a different commitment period.

A tenant wants to use a sale promo code as well as the commitment discount

Promo codes do not stack. Once a commitment period is selected in the booking flow, the manual promo code field is removed, so only the commitment discount applies to that booking.

Auto prepayment next invoice date does not match the rental's Billed until date

Auto prepayment next invoice date (autoPrepayments_billedUntil) is the Add-on's own field and is separate from the rental's native Billed until date. After a renewal, both should advance by the full prepayment period and hold the same value. If they have diverged, contact support@storeganise.com with the unit rental link — do not attempt to correct the field manually, as it is read-only by design.

Ready to get started?

Send us your request and the Storeganise team will install the Automated recurring prepayments Add-on for you.

Request installation
Jump to
Add-on: Automated recurring prepayments