VBS Registration Pro – Documentation

01 Product Scope & Intent

VBS Registration Pro is a seasonal registration system built specifically for churches managing Vacation Bible School and similar structured events. It is designed around three core principles:

1. Local data ownership — all data lives in your WordPress database, not a third-party cloud.
2. Clear lifecycle state management — every registration has a defined, trackable status at all times.
3. Predictable seasonal separation — each event year is logically isolated to keep records clean and reporting accurate.

02 System Architecture Overview

The plugin operates as a modular system inside WordPress. Each component handles a distinct responsibility and communicates through internal hooks and filters.

Data residency: All registration and volunteer data is stored entirely in your WordPress database. No external CRM or cloud database is used. Payment processors are contacted only during transaction processing and confirmation — they do not retain your registration records.

03 Seasons System

A Season represents a specific event cycle (e.g., VBS 2026). Seasons are the top-level organizing structure of the entire plugin. Every registration — kids and volunteer — is stamped with the active season at the time of submission.

The Season system guarantees:

• Registrations from different years never mix in reports or lists
• Historical data is fully preserved when a new season is created
• Admin reporting stays clean and season-specific by default

Typical season lifecycle: Create a new season before registration opens → set it as active → all submissions are attributed to it → when the event ends, create next year’s season and switch → prior season data remains fully accessible for reference, reporting, or export.

04 Data Model

The system manages two independent record types. Kids registrations and volunteer records are stored separately and do not share data.

4.1 Kids Registrations

Each form submission creates one parent-level registration record. That single record can contain multiple children. The structure stores:

• Parent name, email, and phone
• One or more child entries (name, age/grade, and any per-child fields)
• Emergency contact information (if enabled in settings)
• Custom form field data (any fields you’ve added)
• Season label
• Registration status
• Payment metadata — amount, transaction ID, payment method (if applicable)
• Created and updated timestamps

Payment totals are calculated per child. A family registering three children will have one registration record with a combined total reflecting all three.

4.2 Volunteer Registrations

Volunteer records are completely independent from kids registrations and do not interact with the payment system.

• Contact information (name, email, phone)
• Selected role(s)
• Availability windows
• Optional T-shirt size
• Season label
• Submission timestamp

05 Registration Lifecycle

Registrations follow one of two flows depending on whether your event is configured as free or paid.

06 Status Engine

Status is the core control field for every registration. It drives filtering, reporting, bulk email targeting, and admin list views. Keeping statuses accurate is essential for the rest of the system to work reliably.

• Active — Free registration completed and confirmed.
• Pending — Paid registration submitted but payment not yet confirmed.
• Paid — Payment received and verified by the gateway.
• Cancelled — Registration manually cancelled by an admin.

Status can be updated automatically (via lifecycle events like payment confirmation) or manually by an administrator from the registration detail view. Bulk email filters and exports respect status, so accurate status management directly impacts communication accuracy.

07 Payment Processing Architecture

VBS Registration Pro supports Stripe (Checkout + Webhook) and PayPal (IPN confirmation). Both gateways are configured separately in plugin settings and can be toggled independently.

7.1 Stripe Flow

Stripe uses a webhook to notify the plugin after payment. The plugin receives the event, validates the webhook signature using your Stripe secret key, and if valid, updates the registration status to Paid and triggers the confirmation email.

• Requires a valid Stripe webhook endpoint configured in your Stripe dashboard
• Endpoint URL format: yourdomain.com/?vbs_stripe_webhook=1 (check plugin settings for exact URL)
• If the webhook is blocked by a firewall or security plugin, status will remain Pending
• Stripe webhook signing secret must match what is entered in plugin settings
• Test mode and Live mode each have separate webhook endpoints and keys — verify you’re using the correct set

7.2 PayPal Flow

PayPal uses IPN (Instant Payment Notification) to notify the plugin after payment. The plugin receives the IPN message, verifies it with PayPal’s verification API, and if valid, updates the registration to Paid.

• Requires your IPN listener URL entered in your PayPal account settings
• Endpoint URL: yourdomain.com/?vbs_paypal_ipn=1 (check plugin settings for exact URL)
• Sandbox (test) and Live accounts each require their own IPN configuration
• Blocked IPN messages prevent status updates — security plugins and firewalls are the most common cause

08 Email Automation Engine

Emails are event-driven — they fire automatically in response to specific registration lifecycle events. There are no scheduled or batched delivery queues for transactional emails; they send immediately when triggered.

Trigger events include:

• Free mode form submission (immediate confirmation)
• Paid mode payment confirmation received
• Optional admin notification on new registration

Email templates are fully customizable and support dynamic merge tags that are replaced at send-time using the stored registration record:

09 Bulk Communication Engine

The Bulk Email tool is a targeted broadcast layer for communicating with registered families. It is separate from the transactional email engine and does not modify any registration records.

Administrators can:

• Filter recipients by registration status (e.g., send only to Paid registrations)
• Filter by season to reach only the current year’s families
• Automatic recipient de-duplication — one email per parent address regardless of how many children they registered
• Preview recipient count before sending
• Compose and send a custom message directly from the WordPress admin

Bulk messaging is a communication-only layer. It reads registration data for targeting but does not write to it.

10 Export & Reporting

Exports are read-only outputs of your stored data. They do not modify records. Available formats:

All exports respect the active season filter and status filter. Always verify your filter selections before exporting to ensure you’re pulling the correct data set.

11 Administrative Controls

The admin panel provides full control over registrations, volunteers, configuration, and communication from within the WordPress dashboard.

12 Data Ownership & Security

All registration and volunteer data resides in your WordPress database and is owned entirely by your church. It is never transmitted to or stored by Anthropic, vbskids.com infrastructure, or any third-party service.

• Data lives in your WordPress database — on your server or your hosting provider
• No cloud sync, no external CRM, no third-party data storage
• Payment processors only receive transaction data necessary to process checkout
• Sensitive card data never passes through your server
• You can export all data at any time in full without restriction

For improved reliability and security:

• Use an SMTP plugin for transactional email delivery
• Ensure webhook and IPN endpoints are not blocked by WAF or security plugins (Wordfence, iThemes Security, etc.)
• Use SSL (HTTPS) on your site — required for Stripe and strongly recommended for PayPal
• Keep WordPress core, themes, and plugins updated
• Back up your database regularly, especially before plugin updates

13 Common Failure Scenarios

The majority of support issues fall into three root causes. In almost every case, the registration record exists — the issue is with confirmation delivery, not data loss.

14 Maintenance & Updates

Plugin updates are designed to be non-destructive. They preserve all of the following:

• All registration records (kids and volunteer)
• All season data and season labels
• All configuration settings (payment keys, email templates, form fields)
• All export history and custom fields

Best practice checklist before every update:

1. Back up your WordPress database
2. Review the update changelog for any breaking changes or required configuration steps
3. Update during a low-traffic window (not the day registration opens)
4. After updating, verify payment gateway settings are intact
5. Test one free registration and one paid registration end-to-end
6. Confirm webhook/IPN endpoints remain active and reachable

15 Intended Use

VBS Registration Pro is purpose-built for:

• Annual VBS registration (paid or free)
• Seasonal structured church events with defined start/end cycles
• Volunteer coordination tied to a specific event season
• Small to mid-size church event programs that need clean, isolated registration data year over year