ReCurr Tutorial Series — Part 8: Settings Reference
Welcome to the final part of the ReCurr Standard tutorial series. This tutorial provides a complete reference of every setting available in ReCurr, organised by location. Use this as a quick-reference guide when configuring your store.
1. ReCurr Plugin Settings
Location: Subscriptions > Settings
General Tab
| Setting | Type | Default | Description |
|---|---|---|---|
| Failed Payment Retry Count | Number (1–10) | 3 | Number of times ReCurr will automatically retry a failed card payment before placing the subscription on hold. After all retries are exhausted, the subscription status changes to On Hold and both the customer and admin are notified. (v2.8.8) Saved as a whole number: left empty, or not a number, it is saved as 3 — before 2.8.8 an empty count was saved as it was, and a failed card renewal then put the subscription on hold without a retry. |
| Pro-rata billing (monthly) (v2.4.30) | Toggle (On/Off) | On | Controls how monthly subscriptions bill. On (default): the first payment is pro-rated for the rest of the month and renewals fall on the 1st (South African style). Off: the customer pays the full price on signup and renews on the same calendar day each month (anniversary billing). Applies to new monthly sign-ups and trial conversions only — existing subscriptions keep their renewal dates, and weekly/quarterly/annual cycles are unaffected. For Manual EFT, the per-subscription “Pro-rata First Invoice” checkbox defaults to this setting and stays overridable. |
| Variable subscription products (Plus, v2.8.0) | Toggle (On/Off) | Off | Off: only simple products are sold as subscriptions, exactly as before 2.8.0, and a variable product marked as a subscription cannot be bought. On: a variable product can be sold as a subscription — each variation can set its own billing period, trial and annual or quarterly pricing, and uses the parent product’s where it sets none. Selling variable subscriptions requires ReCurr Plus or higher; existing subscriptions keep renewing on every plan. Once you sell variable subscriptions, leave it on: turned off again, their renewals continue at the same amount on the same dates but name the parent product without the options chosen, take stock from the parent, and My Account no longer lists the options. See Plus Tutorial 7: Variable Subscription Products. |
Screenshot 1: Subscriptions > Settings > General tab (Failed Payment Retry Count and the Pro-rata billing toggle).
Subscription Lifecycle Settings (Plus, v2.7.0)
These five settings require a Plus licence and are all off by default. With every one of them off, ReCurr behaves exactly as it did in 2.4.x — no new customer-facing buttons appear, and no billing behaviour changes.
| Setting | Type | Default | Description |
|---|---|---|---|
| Immediate plan switching | Toggle (On/Off) | Off | Master switch for immediate, pro-rated upgrades. When on, a quarterly or annual customer paying by card who moves to a higher plan switches straight away: ReCurr credits their unused time (valued at the full monthly rate) and charges only the difference. Downgrades, lateral moves, monthly/weekly customers and Manual EFT subscriptions all continue to queue to renewal. A consent screen shows the credit, the exact charge, and the new billing date before anything is charged. |
| Immediate downgrades | Toggle (On/Off) | Off | Extends immediate switching to downgrades as well. Requires Immediate plan switching to be on. Leave off to keep downgrades queued to renewal (recommended — a downgrade mid-term forfeits discount value the customer has already paid for). |
| Pro-rata cancellation refunds | Toggle (On/Off) | Off | When on, a mid-term cancellation on a quarterly/annual card subscription refunds the customer’s unused time via the PayFast Refund API and ends access within 24 hours. The free-month benefit of an annual/quarterly discount is never refunded. A failed refund aborts the cancellation cleanly. Late-term cancels where the refund works out to R0 fall back to the standard end-of-period cancellation. Real money leaves your PayFast account — enable deliberately. |
| Cancellation retention flow | Toggle (On/Off) | Off | Replaces the bare “are you sure?” browser prompt with a reason survey, a tailored alternative (change-plan link, or support contact), and a final confirmation. The stated reason is saved against the subscription and emailed to you. Works with or without the refund setting. |
| Pause & resume | Toggle (On/Off) | Off | Lets customers (and admins) freeze a subscription. No billing occurs while paused; on resume the next payment date, end date and licence expiry all shift forward by exactly the paused duration. Capped at 90 days with automatic resume. Works on any billing period and any payment method. Turning this setting off later never strands a paused customer — they can always still resume. |
Screenshot 1b: Subscriptions > Settings > General tab showing the five Plus lifecycle toggles.
Setup guides: Plus Tutorial 4 — Plan Switching, Plus Tutorial 5 — Cancellation Refunds & Retention, Plus Tutorial 6 — Pause & Resume.
Developer filters
| Filter | Purpose |
|---|---|
crb_pause_max_days |
Change the 90-day pause cap. Set to 0 (or any value ≤ 0) for unlimited pauses. |
crb_cancel_reasons |
Customise the options in the cancellation reason survey. |
crb_cancel_support_url |
Set the support link offered for feature/technical/other cancellation reasons (defaults to a mailto to your store’s “From” address, WooCommerce > Settings > Emails — v2.8.8; before, your site’s administration email address). |
crb_payfast_min_charge |
Change the R5 PayFast minimum used by the credit/refund maths. |
crb_payfast_hosted_card_update_available (v2.7.24) |
Opt in to PayFast’s free hosted card-update page. Off by default from v2.7.26, because several South African banks refuse its zero-amount 3D Secure check; Update Card then runs the card registration for everyone. Return true to turn the page on (live mode only — PayFast does not provide it in the sandbox). |
crb_card_registration_amount (v2.7.26) |
The amount charged to register a new card from Update Card, credited in full to the customer’s account (it comes off their next payment). Default 5.00, PayFast’s floor. Raise it only if your PayFast Credit Card → Minimum amount (PayFast dashboard → Settings → Payment Methods) is above R5.00 and you want to keep it there — PayFast otherwise refuses the registration with a 400 error. Values under 5.00 are ignored. |
crb_payfast_cancel_replaced_card (v2.8.8) |
When a customer replaces their card with Update Card, ReCurr cancels the card it replaced at PayFast once the new card is stored, so it can no longer be charged from your PayFast dashboard (never a card another subscription uses). Return false to keep replaced cards active: add_filter( 'crb_payfast_cancel_replaced_card', '__return_false' ); |
Manual EFT Tab
Invoice Schedule
| Setting | Type | Default | Description |
|---|---|---|---|
| Invoice Day | Dropdown (1–28) | 25 | Day of the month when invoices are automatically generated and emailed to Manual EFT subscription customers. We recommend the 25th to align with South African business billing practices (invoice on the 25th, payment due by the 1st). (v2.8.8) Kept to the 1st to the 28th however it is saved; a value that is not a number is saved as the 25th. |
| Payment Terms (v2.7.21) | Number (0–90 days) | 7 | How long a customer has to pay. Saved as a whole number (v2.8.8); the customer’s emails and My Account name it as the date payment is due — “Next invoice: 25 October 2026 (payment due 1 November 2026)”. This is the Due Date printed on the invoice email, and it is also the point from which overdue reminders are counted — the first reminder goes out on the due date, a second a week later, and a final notice a week after that. One setting drives both, so the date you give a customer and the date you start chasing them cannot drift apart. |
Bank Details
These details appear on all Manual EFT invoice emails sent to customers. They are saved as plain text, exactly as typed (v2.8.8).
| Setting | Type | Default | Description |
|---|---|---|---|
| Bank Name | Text | — | Your bank’s name (e.g., FNB, ABSA, Standard Bank, Nedbank, Capitec) |
| Account Name | Text | — | The name on the bank account (e.g., Your Business (Pty) Ltd) |
| Account Number | Text | — | Your bank account number |
| Branch Code | Text | — | Your branch or universal code |
| Account Type | Dropdown | Cheque Account | Cheque Account, Savings Account, or Transmission Account |
If bank details are not configured, a warning notice is displayed on the settings page prompting you to add them before creating Manual EFT subscriptions.
Screenshot 2: Subscriptions > Settings > Manual EFT tab with all fields.
2. PayFast Gateway Settings
Location: WooCommerce > Settings > Payments > PayFast Subscriptions > Manage
| Setting | Type | Default | Description |
|---|---|---|---|
| Enable/Disable | Checkbox | Enabled | Turns the PayFast Subscriptions gateway on or off. When disabled, the gateway will not appear at checkout. |
| Title | Text | Credit/Debit Card (Recurring) | The payment method name customers see at checkout. |
| Description | Textarea | Pay securely. Your card will be saved for automatic renewals. | The description shown below the payment method at checkout. |
| Merchant ID | Text | — | Your PayFast Merchant ID. Required — the gateway will not appear at checkout without it. |
| Merchant Key | Text | — | Your PayFast Merchant Key. Required — the gateway will not appear at checkout without it. |
| Passphrase | Password | — | Your PayFast passphrase for signature generation. Must match the passphrase in your PayFast account exactly. Leave blank if your PayFast account does not have a passphrase set. |
| Test Mode | Checkbox | Enabled | When enabled, payments go to PayFast’s sandbox environment (sandbox.payfast.co.za). When disabled, payments go to the live environment (www.payfast.co.za). Always disable Test Mode before going live. |
Screenshot 3: PayFast Subscriptions gateway settings page showing all fields.
Gateway Visibility Rules
The PayFast Subscriptions gateway only appears at checkout when all of these conditions are met:
- The gateway is enabled
- Merchant ID is entered
- Merchant Key is entered
- The cart contains at least one subscription product
If the cart only contains non-subscription products, the gateway will not appear.
3. Product-Level Subscription Settings
Location: Products > Edit Product > Product data > General tab
These fields appear for Simple products when editing a product — and, with a Plus licence and Variable subscription products on (v2.8.0), for Variable products, where they are the defaults every variation uses (see Variation-Level Fields below).
Core Subscription Fields
| Setting | Type | Default | Description |
|---|---|---|---|
| Enable Subscription | Checkbox | Unchecked | Tick to make this product a subscription product. Reveals additional subscription fields when enabled. |
| Billing Interval | Number (min: 1) | 1 | How many periods between each billing cycle. For example, 1 = every period, 2 = every second period. |
| Billing Period | Dropdown | Month(s) | The billing frequency: Day(s), Week(s), Month(s), Quarter(s), or Year(s). |
Annual Discount Fields
These fields only appear when Billing Period is set to Year(s).
| Setting | Type | Default | Description |
|---|---|---|---|
| Enable Annual Discount | Checkbox | Unchecked | Tick to offer a discount for this annual subscription. Reveals discount type and value fields. |
| Discount Type | Dropdown | Percentage (%) | How the discount is applied: Percentage (%) off the annual total, or Fixed Amount (R) off the annual total. |
| Discount Value | Number (min: 0, step: 0.01) | 0 | The discount amount. Enter 15 for a 15% discount, or 500 for R500 off. |
Plan Switching Fields (Plus)
| Setting | Type | Default | Description |
|---|---|---|---|
| Plan Group | Text (slug) | — | Products sharing the same slug can be switched between by customers. Must be identical across every product in the group (lowercase letters, numbers and hyphens). A product with no group cannot be switched to or from. |
| Plan rank (optional override) (v2.7.0) | Number (positive integer) | — | Only used by immediate plan switching, to decide whether a change is an upgrade (immediate) or a downgrade (queued). Leave blank and ReCurr ranks plans by their monthly price — higher monthly price = higher plan — which is correct for most stores with zero setup. Set a rank (higher = better plan) only where your prices don’t reflect your hierarchy, e.g. a legacy or loss-leader plan. When both products in a comparison have a rank, the rank wins. Ranking never uses the term price or a sale price. |
Screenshot 5b: The Plan Group and “Plan rank (optional override)” fields on the product edit page.
Variation-Level Fields (Plus, v2.8.0)
Location: Products > Edit Product (a Variable product) > Product data > Variations > a variation > ReCurr subscription
Every field defaults to Same as parent — the parent product’s setting, shown in a Parent: … hint beside it. Saving a field on Same as parent stores nothing for it on the variation.
| Setting | Type | Default | Description |
|---|---|---|---|
| Subscription | Same as parent / Yes / No | Same as parent | Whether this option is sold as a subscription. Yes works even when the parent’s Enable Subscription is unticked (buy once or subscribe). |
| Billing Interval, Billing Period | Number / Dropdown | Same as parent | This option’s own term — for example a Yearly option beside Monthly ones. |
| Free Trial, Trial Duration | Same as parent / Yes / No; 7, 14, 21 or 28 days | Same as parent | In the variation’s row of checkboxes. A trial longer than one billing period of the option is refused on save. |
| Custom Annual Price (R), Annual Discount, Annual Discount Type, Annual Discount Value | As on a simple product | Same as parent | Shown when the option bills Year(s). |
| Custom Quarterly Price (R), Quarterly Discount, Quarterly Discount Type, Quarterly Discount Value | As on a simple product | Same as parent | Shown when the option bills Quarter(s). |
| Plan Rank | Number | Same as parent | Shown on licences with plan switching. |
Set on the parent only, never per variation: Billing Cycle Toggle (not available on a variable product at all), Available billing cycles, Plan Group. Each variation’s Regular price follows the same rule as a simple product’s. Messages you can meet on save are listed in Plus Tutorial 8: Troubleshooting Variable Subscriptions.
Discount Preview
When an annual discount is configured, a live preview box appears showing:
- Monthly base price
- Annual base price (monthly x 12)
- Discount amount
- Final annual price after discount
- Monthly equivalent of the discounted price
- Total customer savings
This preview updates in real time as you change values.
Important Notes
- Regular price = the price of one billing period, unless an annual or quarterly price setting says otherwise (v2.7.29) — For a monthly product the Regular price is the monthly price. For an annual or quarterly product with no discount and no custom price, the Regular price is charged as it stands, once per billing period — enter the yearly (or quarterly) price. With Enable Annual Discount ticked (or the quarterly discount), the Regular price is the monthly base: ReCurr charges twelve (or three) times it, less the discount. A Custom Annual Price or Custom Quarterly Price (Plus) is charged as entered. Whichever applies, the product page, checkout, the recorded subscription amount, trial conversions, manual EFT invoices and plan switches all use the same figure. Products with the billing cycle toggle always use the Regular price as the monthly base.
- Simple products — and variable products on Plus (v2.8.0) — Subscription fields appear on Simple products, and on Variable products when you have Plus and Variable subscription products is on. They never appear on Grouped or External products.
Screenshot 4: Product edit page showing all subscription fields (Enable Subscription, Billing Interval, Billing Period).
Screenshot 5: Annual discount fields and the live preview box (with Billing Period set to Year).
4. License Settings
Location: Subscriptions > License
| Setting | Type | Description |
|---|---|---|
| License Key | Text | Your ReCurr license key, provided in your purchase confirmation email from CyberDummies. Required to activate the plugin features. |
Enter your license key and click Activate License. The page displays the current license status (Active or Inactive).
Screenshot 6: Subscriptions > License page.
5. Automated Background Tasks
ReCurr uses WordPress Cron to run background tasks automatically. These are not configurable via the admin interface but are important to understand.
| Task | Schedule | Purpose |
|---|---|---|
| Process Renewals | Recurring | Checks for card subscriptions due for renewal and processes payments automatically. Excludes Manual EFT subscriptions. Processes up to 50 subscriptions per run. Paused subscriptions are never selected, so they are never billed (Plus, v2.7.0). This job also auto-resumes any subscription that has been paused longer than the 90-day cap — a just-resumed subscription is never charged on the same run. |
| Retry Failed Payments | Recurring | Retries failed card payments for subscriptions that haven’t exceeded the retry count. |
| Trial Reminders & End | Recurring | For no-card trials: sends the 72h / 48h / 24h “add your card” magic-link reminders, and at trial end moves any trial without a card to On Hold with a 7-day grace period. |
| Grace-Period Cleanup | Hourly | Auto-cancels on-hold trials whose 7-day grace period has lapsed with no card added. The customer is never charged. |
| Process Manual Invoices | Daily at 6:00 AM | Generates the invoices that are due for active Manual EFT subscriptions and emails them to customers, on the configured invoice day. (v2.8.8) It looks at every subscription every day, so a morning on which it did not run is caught up at the next run — every period invoiced once, one invoice per subscription per run, every date kept on the invoice day. |
| Chase Overdue Invoices (v2.7.21) | Daily at 7:00 AM | Finds Manual EFT invoices that are past their Payment Terms and still unpaid, emails the customer a reminder at each of the three stages, and sends you a summary of everything outstanding. Runs an hour behind the invoice job so an invoice raised that morning is never chased on the same day. It never suspends or cancels anything — that stays your decision. |
| Licence Expiry & Domain Sweep (v2.7.21) | Daily | Marks licence keys whose expiry date has passed as expired, and releases the domain registered against them. Only relevant if you use the licensing features. A key expired this way is revived automatically, domain included, the moment its subscription is paid. |
Reliability (v2.4.30, extended in v2.7.21): the renewal, payment-retry, trial-end, invoice, overdue-chase and licence-sweep jobs are all self-healing — if a site’s scheduled events are ever lost (host migration, a cron-reset plugin, or a database restore), they re-register automatically so billing keeps running. This matters more than it sounds: a scheduled job that is registered only once, at activation, and never checked on again will stop permanently and silently the first time anything clears it, with nothing anywhere to tell you. That is exactly how licence expiry stopped working before v2.7.21.
WordPress Cron Note
WordPress Cron is triggered by site visits. On low-traffic sites, cron jobs may not run at the exact scheduled time. If your invoices or renewals are not processing on time, consider setting up a real server cron job via your hosting control panel to trigger WordPress Cron regularly:
*/15 * * * * wget -q -O - https://yoursite.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1
This runs WordPress Cron every 15 minutes, ensuring invoices and renewals are processed promptly.
6. Settings Quick-Reference by Task
“I want to…”
| Task | Where to Go |
|---|---|
| Change how many times failed payments are retried | Subscriptions > Settings > General > Failed Payment Retry Count |
| Change what day invoices are generated | Subscriptions > Settings > Manual EFT > Invoice Day |
| Change how long customers have to pay, and when chasing starts | Subscriptions > Settings > Manual EFT > Payment Terms |
| See every unpaid invoice, oldest first | Invoices > Unpaid |
| Check whether an invoice email actually reached the customer | Invoices > Unpaid — look for the Not sent flag beside Resend |
| Stop WooCommerce deleting unpaid invoices | WooCommerce > Settings > Accounts & Privacy > Retain pending orders (clear it) |
| Update bank details on invoices | Subscriptions > Settings > Manual EFT > Bank Details |
| Enable or disable the payment gateway | WooCommerce > Settings > Payments > PayFast Subscriptions |
| Switch between sandbox and live mode | WooCommerce > Settings > Payments > PayFast Subscriptions > Test Mode |
| Update PayFast credentials | WooCommerce > Settings > Payments > PayFast Subscriptions > Merchant ID / Key / Passphrase |
| Change the payment method name at checkout | WooCommerce > Settings > Payments > PayFast Subscriptions > Title |
| Make a product a subscription | Products > Edit Product > Product data > General > Enable Subscription |
| Set the billing frequency | Products > Edit Product > Product data > General > Billing Period |
| Add an annual discount | Products > Edit Product > Product data > General > Enable Annual Discount (requires Billing Period = Year) |
| Activate or check your license | Subscriptions > License |
| View all subscriptions | Subscriptions > All Subscriptions |
| Create a Manual EFT subscription | Subscriptions > Add New Subscription |
| Let customers upgrade immediately with pro-rata credit (Plus) | Subscriptions > Settings > General > Immediate plan switching |
| Refund customers for unused time when they cancel (Plus) | Subscriptions > Settings > General > Pro-rata cancellation refunds |
| Ask customers why they’re cancelling (Plus) | Subscriptions > Settings > General > Cancellation retention flow |
| Let customers freeze a subscription (Plus) | Subscriptions > Settings > General > Pause & resume |
| Make products switchable (Plus) | Products > Edit Product > Product data > General > Plan Group |
7. WooCommerce Settings That Affect ReCurr
These are standard WooCommerce settings, not ReCurr-specific, but they impact how ReCurr operates.
| Setting | Location | Impact |
|---|---|---|
| Currency | WooCommerce > Settings > General | Determines currency for all subscription prices and invoices (set to ZAR for South African Rand) |
| Store Address | WooCommerce > Settings > General | Used for tax calculations and PDF invoice business address |
| Email Sender | WooCommerce > Settings > Emails | The “From” name and email address on all ReCurr emails, to customers and to you, and the address customers are asked to write to (v2.8.8 — before, ReCurr’s emails came from “WordPress” unless a mail plugin set the sender) |
| Admin Email | Settings > General (WordPress) | Where admin notification emails are sent |
| Permalinks | Settings > Permalinks | Must be set to something other than “Plain” for the My Account subscriptions endpoint to work |
| Retain pending orders | WooCommerce > Settings > Accounts & Privacy | Check this one. A Manual EFT invoice stays in the pending status until it is paid, because that is what keeps its Pay Now link working. This setting moves every pending order older than the window you choose to the trash, daily, with no notice. Before v2.7.21 that silently deleted unpaid invoices along with the customer’s payment link. ReCurr’s own invoices are now exempt, but the setting still applies to every other order on your store, so leave it blank unless you have a specific reason. |
| Retain failed orders / Retain cancelled orders | WooCommerce > Settings > Accounts & Privacy | Same mechanism as above. ReCurr invoices are exempt from these too, from v2.7.21. |
| High-Performance Order Storage | WooCommerce > Settings > Advanced > Features | ReCurr is fully compatible with both HPOS and the older post-based storage. HPOS is the default on recent WooCommerce installs and is recommended. |
Summary
All ReCurr settings are found in four locations:
| Location | What You’ll Find |
|---|---|
| Subscriptions > Settings | Retry count, pro-rata toggle, invoice day, bank details, and the Plus lifecycle toggles (immediate switching, cancellation refunds, retention flow, pause & resume) |
| Subscriptions > License | License key activation |
| WooCommerce > Settings > Payments | PayFast gateway credentials, test mode |
| Products > Edit Product | Per-product subscription fields, billing period, discounts, plan group and plan rank |
Tutorial Series Complete
Congratulations — you’ve completed the full ReCurr tutorial series. You now have everything you need to install, configure, and manage recurring subscriptions on your WooCommerce store.
All Tutorials
| Tutorial | Topic |
|---|---|
| 1. Getting Started | Install, activate, and initial configuration |
| 2. Creating Subscription Products | Billing periods, pricing, and discounts |
| 3. Configuring PayFast | Gateway credentials, sandbox vs live, ITN setup |
| 4. Managing Subscriptions | Admin dashboard, status management, details |
| 5. Manual EFT Subscriptions | Corporate clients paying via bank transfer |
| 6. Customer Experience | Checkout flow and My Account subscription management |
| 7. Invoicing | Invoice generation, PDF attachments, email delivery |
| 8. Settings Reference | Complete reference of all available settings (you are here) |
Need Help?
- Email: [email protected]
- Support Hours: Monday to Thursday, 9:00 AM – 4:00 PM (SAST)
Friday, 09:00 AM – 12:00 PM (SAST) - Website: cyberdummies.co.za/recurr
We Are Here To Help!
Office
Queenswood
Pretoria
SA
Hours
M-T: 9am – 4pm
F: 9am – 12pm
S-S: Closed
Email Us
Let's Chat
