Recurring Billing Orders - Staff Guide

Last Updated: October 13, 2025 Version: 1.0

Overview

This guide explains how to set up recurring billing orders for customers who rent equipment on an ongoing basis (monthly, weekly, etc.). The system will automatically charge their saved credit card on the billing date.

Prerequisites

Before creating a recurring billing order, ensure:

1. ✅ Customer has a saved payment profile (credit card on file)
2. ✅ Customer has auto-charge enabled on their account
3. ✅ Equipment is already onsite or will be delivered

Part 1: Enable Auto-Charge for Customer

IMPORTANT: This must be done BEFORE creating the recurring order.

Steps:

1. Navigate to the customer's company page

   • Example: https://admin.quarryrents.com/companies/14

2. Click "Edit Company" button (top right)

3. Scroll to "Billing Automation" section

4. Check the box: ☑️ "Enable automatic credit card charging"

   • This allows the system to automatically charge saved cards
   • Charges run daily at 8:00 AM

5. Click "Update Company"

Verify Payment Profile:

Before proceeding, verify the customer has a card on file:

• On the company page, scroll to "Payment Methods" section
• Look for cards with blue "Auth.Net CIM" or purple "Fiserv" badges
• Ensure at least one card shows "Default" badge (this will be charged)
• Check expiration date is not expired

Part 2: Create Recurring Billing Order

Navigate to New Order:

Option A: From customer page

• Click customer → "Create Order" button

Option B: Direct URL

• Go to: https://admin.quarryrents.com/orders/new

Fill Out Order Form:

1. Basic Information

• Company: Select the customer
• Contact: Select primary contact
• Product: Choose the equipment/service

2. Delivery Information

• Delivery Address: Enter or select saved address
• Delivery Date:
  • If equipment already onsite: Use the date it was delivered
  • If new order: Use today or future delivery date
• Pickup Date: Leave blank for recurring orders

3. Pricing

• Rental Amount: Enter the recurring charge amount (e.g., $500)
• Delivery Fee: If applicable
• Taxes: Will auto-calculate

4. Recurring Billing Settings

CRITICAL SECTION - PAY CLOSE ATTENTION:

• ☑️ Is Recurring: Check this box

• Billing Frequency: Select from dropdown

  • Monthly
  • Weekly
  • Bi-weekly
  • Quarterly

• Billing Start Date: VERY IMPORTANT

  • This is the date of the FIRST automatic charge
  • Example scenarios:
    • Equipment already onsite, next charge due 10/15/2025 → Set to 10/15/2025
    • New order starting today (10/13) → Set to 10/13/2025 if charging immediately, or 11/13/2025 for one month from now
  • ⚠️ System will NOT charge until this date

• Payment Profile: The saved card will auto-select (shows default card)

  • Only change if customer requests specific card

5. Notes (Optional)

• Add any internal notes about the recurring service

Save the Order:

Click "Create Order" button

Part 3: Activate Recurring Billing

After creating the order, you must mark it as "Delivered" to activate auto-charging.

Steps:

1. On the order detail page, find the "Mark as Delivered" button

   • Usually in the top right or action menu

2. Click "Mark as Delivered"

3. Confirm the action

What Happens Behind the Scenes:

When you mark as delivered:

• ✅ Order status changes to "delivered"
• ✅ System calculates next_billing_date from billing_start_date
• ✅ Order is now active for automatic charging
• ✅ Shows on recurring billing dashboard

Understanding the Billing Timeline

Example Scenario:

Today: October 13, 2025 Customer: Lynn Baksinski Equipment: 20-yard dumpster (already onsite) Next renewal: October 15, 2025 Monthly rate: $500

Timeline:

Key Points:

• ❌ Does NOT charge immediately when order created
• ❌ Does NOT charge when marked as delivered
• ✅ ONLY charges on billing date at 8:00 AM
• ✅ Automatic charges run daily at 8:00 AM
• ✅ System checks all orders where next_billing_date = today

Monitoring Recurring Billing

Recurring Billing Dashboard:

Navigate to: https://admin.quarryrents.com/recurring_billing

This shows:

• All active recurring orders
• Next billing dates
• Billing status (pending, active, failed)
• Payment profiles used

What to Check:

• ✅ Order shows in "Active" tab
• ✅ Next billing date is correct
• ✅ Payment profile shows (not "No profile on file")
• ✅ Customer has auto-charge enabled

Troubleshooting

Problem: Order not charging automatically

Check these items:

1. ✅ Company has auto_charge_enabled = true

   • Go to company edit page
   • Verify checkbox is checked

2. ✅ Order status is "delivered"

   • Go to order detail page
   • Status should show "Delivered" not "Pending"

3. ✅ Order is marked as recurring

   • Check "Is Recurring" field on order

4. ✅ Next billing date is today or in the past

   • If date is in future, system won't charge yet

5. ✅ Payment profile exists and is not expired

   • Check company payment methods section
   • Verify expiration date

Problem: Card declined

When a card is declined:

• ❌ Order status → "payment_failed"
• 📧 Email sent to customer: "Payment failed - update card"
• 📧 Email sent to admin: "Recurring payment failed"
• ⚠️ next_billing_date does NOT advance (will retry next day)

Staff Action Required:

1. Contact customer to update payment method
2. Or manually process payment
3. Once resolved, system will try again tomorrow

Problem: Card expired

When a card expires:

• 📧 Email sent to customer: "Card expired - update required"
• ⚠️ Order shows warning on dashboard

Staff Action Required:

1. Contact customer to provide new card
2. Either:
   • Customer calls in with new card details, OR
   • Send customer secure payment link (Fiserv)

Common Scenarios

Scenario 1: Converting Existing Customer to Recurring

Customer has been paying manually, wants to switch to auto-pay:

1. Enable auto-charge on company ✅
2. Ensure customer has card on file ✅
3. Create new recurring order with:
   • billing_start_date = date of next expected payment
   • billing_frequency = how often they currently pay
4. Mark as delivered ✅
5. (Optional) Archive/cancel old manual orders

Scenario 2: Equipment Already Onsite

Equipment was delivered weeks ago, customer now wants recurring billing:

1. Determine when next payment is due (e.g., 10/15/2025)
2. Create order with:
   • delivery_date = original delivery date (past)
   • billing_start_date = next charge date (10/15/2025)
3. Mark as delivered immediately
4. System will charge on 10/15/2025

Scenario 3: New Order Starting Today

Customer orders today, wants to start recurring billing immediately:

1. Create order with:
   • delivery_date = today
   • billing_start_date = today (for immediate charge) OR tomorrow/next month
2. Deliver equipment
3. Mark as delivered
4. System will charge at 8:00 AM on billing_start_date

Scenario 4: Customer Owes Back Payments

Equipment onsite for 2 months, customer hasn't paid, now wants recurring:

Option A: Create invoice for back-owed amount

1. Create manual invoice for past 2 months
2. Collect payment or mark as due
3. Then create new recurring order for future

Option B: Include in first recurring charge

1. Create recurring order with higher initial amount
2. Set notes explaining first charge includes back payments
3. After first charge, amount returns to normal

Email Notifications

The system automatically sends emails for recurring billing events:

To Customer:

1. Payment Success (recurring_payment_receipt.html.erb)

   • Subject: "Payment Receipt - [Order Number]"
   • Includes: Amount charged, card used, next billing date

2. Payment Failed (recurring_payment_failed.html.erb)

   • Subject: "Payment Failed - Action Required"
   • Includes: Reason, how to update card

3. Card Expired (card_expired_update_required.html.erb)

   • Subject: "Card Expired - Please Update"
   • Includes: Expired card details, how to update

To Admin:

1. Payment Failed Alert (recurring_payment_failed_admin.html.erb)

   • Subject: "ALERT: Recurring Payment Failed - [Customer Name]"
   • Includes: Customer details, failure reason, next steps

2. Daily Summary (recurring_charge_summary.html.erb)

   • Subject: "Daily Recurring Billing Summary"
   • Sent at 9:00 AM (after 8:00 AM charges complete)
   • Includes: Total charges, successes, failures, total revenue

Best Practices

Do's:

✅ Always enable auto-charge BEFORE creating the order ✅ Verify card is not expired before setting up recurring billing ✅ Double-check billing_start_date - this determines when charges start ✅ Mark as delivered after creating the order ✅ Add notes about the recurring arrangement for future staff ✅ Check recurring billing dashboard daily for any failures

Don'ts:

❌ Don't create recurring order without auto-charge enabled ❌ Don't forget to mark as delivered (order won't charge) ❌ Don't set billing_start_date to wrong date (will charge on wrong day) ❌ Don't assume customer has card on file (always verify first) ❌ Don't set pickup_date on recurring orders (leave blank)

Quick Reference Checklist

Use this checklist when creating a recurring order:

Pre-Setup:

• [ ] Customer has card on file
• [ ] Card is not expired
• [ ] Auto-charge enabled on company

Order Creation:

• [ ] Company selected
• [ ] Product selected
• [ ] Delivery address filled
• [ ] Delivery date set (may be past date)
• [ ] Rental amount entered
• [ ] ☑️ "Is Recurring" checked
• [ ] Billing frequency selected (monthly, weekly, etc.)
• [ ] Billing start date set correctly (first charge date)
• [ ] Payment profile shows (default card)

Activation:

• [ ] Order created successfully
• [ ] Order marked as "Delivered"
• [ ] Order shows on recurring billing dashboard
• [ ] Next billing date displays correctly

Verification:

• [ ] Customer notified about recurring billing setup
• [ ] Customer understands charge date and frequency
• [ ] Note added to order about recurring arrangement

Technical Details (For Admins)

Automatic Charging Process:

Job: RecurringCardChargeJob Schedule: Daily at 8:00 AM Configuration: config/recurring.yml

Process Flow:

1. Job runs at 8:00 AM
2. Finds all orders where:
   • is_recurring = true
   • status = 'delivered'
   • next_billing_date = TODAY
   • company.auto_charge_enabled = true
3. For each order:
   • Gets payment profile
   • Calls RecurringCardChargeService
   • Routes to correct processor (Auth.Net or Fiserv)
   • Charges card
   • Updates next_billing_date to next cycle
   • Sends emails
4. Generates daily summary email at 9:00 AM

Payment Processor Routing:

The system automatically routes to the correct processor:

• Authorize.Net CIM: Legacy cards (blue badge)

  • Uses AuthorizeNetPaymentService
  • Production endpoint: https://api.authorize.net/xml/v1/request.api

• Fiserv: New cards (purple badge)

  • Uses FiservPaymentService
  • Production endpoint configured in ENV

Database Fields:

Order model:

• is_recurring (boolean) - Marks order as recurring
• billing_frequency (string) - "monthly", "weekly", "bi_weekly", "quarterly"
• billing_start_date (date) - Date of first charge
• next_billing_date (date) - Date of next automatic charge
• payment_profile_id (integer) - Which card to charge

Company model:

• auto_charge_enabled (boolean) - Master switch for auto-charging

Support

If you encounter issues with recurring billing:

1. Check this guide first
2. Review recurring billing dashboard
3. Check customer's payment profile status
4. Contact technical support with:
   • Order number
   • Customer name
   • Error message (if any)
   • Screenshots of issue

Changelog

Version 1.0 (October 13, 2025)

• Initial guide created
• Covers Auth.Net CIM integration
• Includes Fiserv payment routing
• Added troubleshooting section
• Added common scenarios