Scheduled Changes and Reminders

Boathouse provides a comprehensive scheduled changes system that allows customers to schedule subscription plan downgrades to take effect at their next billing cycle. The system automatically sends email reminders 24 hours before changes take effect, giving customers a final opportunity to cancel unwanted changes.

What Are Scheduled Changes?

Scheduled changes are primarily used for subscription plan downgrades that customers want to take effect at their next billing cycle. This prevents immediate charges and ensures a smooth transition when customers want to reduce their plan.

Key Benefits

• No Immediate Charges: Downgrades take effect at the next billing cycle, avoiding prorated charges
• Customer Control: Customers can schedule changes in advance and cancel them if they change their mind
• Automatic Execution: Changes happen automatically without customer or admin intervention
• Clear Communication: Customers receive reminders and confirmations throughout the process

How It Works for Customers

1. Customer Initiates Change: Customer selects a lower-tier plan through your customer portal
2. Change Scheduled: Instead of immediate execution, the change is scheduled for the next billing cycle
3. Confirmation: Customer receives confirmation that the change is scheduled
4. Reminder Email: 24 hours before execution, customer receives a reminder email
5. Automatic Execution: Change takes effect 12 hours before the next billing date
6. Billing Continues: Customer is billed for the new plan on their next billing cycle

Timing and Execution

When Changes Take Effect

Scheduled changes are executed 12 hours before the customer's next billing date. This timing ensures:

• No billing interruptions or gaps in service
• Smooth transition to the new plan
• Customer is immediately billed for the new plan amount
• No prorated charges (using Paddle's do_not_bill proration mode)

Example Timeline

If a customer's next billing date is January 15th at 2:00 PM UTC:

• January 13th at 2:00 PM UTC: Reminder email sent (24 hours before execution)
• January 14th at 2:00 PM UTC: Scheduled change executes (12 hours before billing)
• January 15th at 2:00 PM UTC: Customer billed for new plan amount

Customer Experience

Scheduling a Downgrade

When customers want to downgrade their plan:

1. They access your customer portal (built with Boathouse)
2. Select the "Change Plan" option
3. Choose a lower-tier plan
4. System automatically detects this is a downgrade
5. Instead of immediate execution, the change is scheduled
6. Customer sees confirmation: "Your plan will change to [New Plan] on [Date]"

Managing Scheduled Changes

Customers can view and manage their scheduled changes through the customer portal:

• View Pending Changes: See what changes are scheduled and when they'll take effect
• Cancel Changes: Cancel scheduled changes if they change their mind (before execution)
• Change History: View previously executed scheduled changes

Cancellation Options

Customers have multiple ways to cancel scheduled changes:

• Customer Portal: Direct access through the portal interface
• Reminder Email: One-click cancellation link in the 24-hour reminder

Reminder Email System

24-Hour Reminder

Customers automatically receive a reminder email 24 hours before their scheduled change takes effect. This email includes:

• Clear Timeline: "Your plan change is scheduled for tomorrow"
• Plan Details: Current plan vs new plan comparison
• Pricing Information: New plan pricing and billing cycle
• Cancellation Button: One-click link to cancel the change
• Portal Access: Link to manage their subscription

Cancellation Deep Linking

The cancellation button in reminder emails uses smart deep linking to provide a seamless experience:

• Takes customers directly to the cancellation confirmation screen
• No navigation or login required
• Secure HMAC signature ensures authenticity
• Works with custom domains if configured

Data Storage

Scheduled changes are stored in Boathouse but also in the custom data of a subscription in Paddle which is the master data for any changes. That means if you remove or change the custom data for that subscription relating to a scheduled change, then this will dictate what Boathouse does when the time comes to make the change.

Validation Checks

Before executing any scheduled change, the system validates:

• ✅ Subscription still exists and is active
• ✅ Customer hasn't cancelled their subscription
• ✅ Current plan matches what was expected when change was scheduled
• ✅ Paddle still has the scheduled change information
• ✅ Timing is appropriate (within execution window)

Custom Data Storage

Scheduled change information is stored in Paddle's subscription custom_data field:

{
  "boathouse_scheduled_change": {
    "action": "change_price",
    "old_price_id": "pri_current_plan",
    "new_price_id": "pri_new_plan"
  }
}