SaaS Setup Guide.

This guide walks you through the full SaaS enablement path, from initial plan configuration to verifying that everything works. Follow the steps in order; each one builds on the previous.

Who is this for? Network operators, white-label agencies, and anyone running Reward Loyalty as a multi-tenant platform where partners (businesses) sign up, receive plan-based limits, and manage their own loyalty programs. If you run a single business, you don't need this guide.

Step 1: Configure Plan Tiers

Plan tiers define what each partner can do. All plans live in config/plans.php.

The default configuration ships with four tiers:

Each tier sets:

• Resource limits: loyalty cards, stamp cards, vouchers, members, staff, rewards
• Feature flags: voucher campaigns, email campaigns, Agent API access
• Pricing: monthly and yearly prices in minor units (cents for USD)
• Display: localized names via translation keys, sort order, visibility

The one marked 'is_default' => true is assigned to every new partner, whether created by an admin or through self-registration.

Important: config/plans.php is a protected file. After your first installation, future updates will not overwrite your customized plan configuration.

📖 See Partner Registration: Plan Configuration for the full field reference and pricing/minor-unit details.

Step 2: Choose a Billing Mode

Reward Loyalty supports two billing modes. Choose one:

Option A: Manual Billing (Default)

No configuration needed. This is the default when BILLING_PROVIDER is not set in .env.

• Admins assign plans via the partner management CRUD
• You invoice partners through your accounting software (QuickBooks, Xero, bank transfers, etc.)
• All partners are treated as fully active, with no billing restrictions

Best for: Agencies, network operators, and white-label deployments where you already have a billing relationship with partners.

Option B: Stripe Billing

Set BILLING_PROVIDER=stripe in .env and configure API keys, webhook secret, and price IDs.

• Stripe manages subscription lifecycle via webhooks
• Self-registered partners can subscribe directly from the billing page. Stripe Checkout creates the customer automatically.
• Admin-created partners without Stripe IDs are treated as legacy (full access, admin-managed)
• Existing subscribers manage their plan via the Stripe billing portal

Best for: Operators who want automated subscription billing with payment processing.

What Stripe mode does: Webhook-driven subscription sync, self-service Checkout for new self-registered partners, billing portal for existing subscribers, and subscription status on the partner billing page. Admin-created partners remain admin-managed until an admin links them to a Stripe customer. Self-registered partners (those who signed up via the registration page) can initiate Stripe Checkout themselves. Cashier creates the Stripe customer during the checkout session.

📖 See Billing Configuration for the full Stripe setup, including API keys, webhook endpoint, price IDs, and Health Center diagnostics.

Step 3: Set Up Your Primary Network

Networks organize partners into groups. One network must be marked as primary and active. This is required for partner self-registration.

Fresh Installations

The installer creates a Default network that is active, primary, and uses your platform currency. No action needed unless you want to rename it or add more networks.

Existing Installations

1. Go to Admin → Networks
2. Ensure at least one network exists
3. Mark it as Active and Primary
4. Set the network's Currency. This becomes the default currency for self-registered partners.

Single-primary enforcement: When you mark a network as primary, all other networks are automatically cleared. Only one primary network can exist at any time.

Currency inheritance: Self-registered partners inherit the primary network's currency. Partners can change their currency afterward via their profile.

📖 See Understanding Networks for network management details.

Step 4: Enable Partner Self-Registration (Optional)

Partner self-registration is disabled by default. Most operators prefer creating partner accounts manually. If you want partners to sign up themselves:

1. Go to Settings → Onboarding → Partner Registration
2. Enable the toggle

Or set APP_PARTNERS_CAN_REGISTER=true in .env as a fallback default (the database setting takes precedence once saved).

What happens when a partner registers:

1. They fill in business name, email, and consent
2. They verify their email via a one-time code
3. They receive the default plan (is_default in config/plans.php)
4. They are assigned to the primary network
5. They inherit the primary network's currency
6. Their resource limits and feature flags are derived from the default plan

Prerequisites for registration to work:

• Registration must be enabled (Step 4)
• An active primary network must exist (Step 3)

If either is missing, registration is blocked with a clear error message.

📖 See Partner Registration for the full registration flow, plan comparison cards, and troubleshooting.

Step 5: Verify Your Setup

After completing the steps above, verify everything is working:

Health Center

Go to Admin → Health Center and check:

📖 See Health Center for all diagnostic checks.

SaaS Dashboard

Go to Admin → SaaS Overview to see:

• Partner Status Breakdown: All partners and their subscription states
• Plan Distribution: How partners are spread across tiers
• Attention Required: Expiring trials, past-due partners
• Recent Registrations: Latest partner signups
• Usage Overview: Aggregate resource counts

📖 See SaaS Dashboard for details on each section.

Test Registration (if enabled)

1. Open a private/incognito browser window
2. Navigate to your platform's partner registration page
3. Register with a test email
4. Verify you receive the OTP code and can complete registration
5. Confirm the test partner appears in Admin → Partners with the correct plan, network, and currency

Step 6: Ongoing Operations

Partner Management

• Create partners manually via Admin → Partners → Add
• Assign or change plans via the partner edit page. Limits and features update immediately.
• Override individual permissions via Partner Permissions. Overrides persist across plan changes.
• Export partner data: CSV/JSON export from the partner list

Monitoring

• SaaS Dashboard: Daily overview of subscription health and platform growth
• Health Center: System diagnostics and service status
• Activity Logs: Audit trail for all admin and partner actions

Partner Experience

Each partner sees a My Plan page with:

• Current plan name, description, and status badge
• Feature gates (enabled/disabled for their tier)
• Resource usage progress bars (cards, staff, members, etc.)
• Available plans comparison (Stripe mode, always visible)
• Upgrade / Change Plan buttons (Stripe mode, self-registered partners only)
• Manage Billing portal link (Stripe mode, existing subscribers only)

Note: Admin-created and legacy partners see plan cards but no self-service action buttons. They must contact the administrator for plan changes.

📖 See Billing Configuration: Partner Billing Page for details.

Quick Checklist

Use this to verify your SaaS setup is complete:

• config/plans.php: Plan tiers configured with correct limits, pricing, and one is_default
• .env: Billing provider set (BILLING_PROVIDER= for manual, BILLING_PROVIDER=stripe for Stripe)
• Stripe credentials: STRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET (Stripe mode only)
• Stripe price IDs: Mapped in .env for each paid tier (Stripe mode only)
• Primary network: One active, primary network with currency set
• Partner registration: Enabled in Settings → Onboarding (if desired)
• Health Center: All checks green
• SaaS Dashboard: Accessible and showing correct data
• Test registration: Completed successfully (if registration is enabled)

Related Topics

• Billing Configuration: Manual and Stripe billing setup
• SaaS Dashboard: Partner subscription monitoring
• Partner Registration: Self-registration flow and plan comparison
• Partner Permissions & Limits: Fine-grained access control
• Health Center: System diagnostics
• Who Is This For?: Business models and expectations