Subscription billing

Overview

Subscription billing is what your business pays Mallard Bay for using the platform (your software plan). It runs through Stripe’s billing experience and is separate from money guests pay you for bookings, Quick Pay links, and your Stripe connected account used for payouts.

In the dashboard today, the main outfitter-facing entry points are: opening the Billing path (/billing), following a /billing-portal link that includes a code, and using Request subscription changes in your profile menu (which sends you to a Mallard Bay web form). Detailed plan breakdowns visible inside the dashboard (tier name, billing period dates, bundled products/add-ons/promotions) appear in workflows that this codebase exposes to Mallard Bay operators, not as a standalone “subscription summary” screen for every outfitter user—your live subscription details after using Billing are largely what Stripe shows in the portal unless Mallard Bay provides them elsewhere.

Prerequisites

• A normal dashboard login when you use Account settings, Stripe dashboard (guest payouts), or Request subscription changes from the profile menu.
• The /billing and /billing-portal routes are implemented so they do not require dashboard authentication before redirecting; you may briefly see a loader, then you leave the dashboard for Stripe (or hit an error if configuration is missing). Exact Stripe sign-in behavior depends on Stripe and how your customer portal is set up.
• Billing owner settings (who receives booking payouts via Stripe Connect) concern booking payments, not Mallard Bay’s software subscription—you can see billing owner info in outfitter Manage / settings-type areas where that card is surfaced, but that is distinct from /billing.

Step-by-step: using subscription billing from the dashboard

1. Open Billing (/billing)

1. Sign in if you’re working from other dashboard areas first.
2. Go to /billing on your Mallard Bay admin host (same place as the rest of the dashboard; canonical path /billing).
3. The page redirects you to Stripe’s customer billing portal using a centrally configured billing portal URL.

You use this flow to manage Mallard Bay subscription logistics that Stripe exposes in the portal (for example invoices, payment method, cancellation—whatever your Stripe customer portal is configured to allow). If the billing portal URL is not configured for the deployed app, this repository’s page surfaces an error state instead of redirecting—the exact wording is not spelled out beyond a generic loading/error container in code.

2. Use a link with /billing-portal and a code (when Mallard Bay sends one)

Sometimes you receive a dashboard URL shaped like /billing-portal?code=….

1. Open the link exactly as provided.
2. The app asks the Mallard Bay API for a stripeBillingPortalUrl tied to that code, then redirects in-app navigation to Stripe.

If you strip the code query parameter, this path has nothing to look up and will not behave as intended. This pattern is suited to session-specific, targeted portal links.

3. Request subscription changes (plans, tiers, add-ons Mallard Bay must handle)

When you want to upgrade, downgrade, or otherwise change plan features Mallard Bay controls outside the Stripe self-serve portal:

1. Open your profile menu (account menu in the header).
2. Choose Request subscription changes.
3. You are taken to {Mallard Bay root website}/for-guides/subscription-requests (configured from environment; the slug is subscription-requests under the for-guides section of the public site).

The dashboard copies for feature limits elsewhere often tell you to reach out to your account manager for upgrades when a capability is gated—use Request subscription changes plus any direction you’ve gotten from Mallard Bay so requests go through the intended channel.

4. Do not confuse other “billing” shortcuts

These exist in or near product navigation but solve different problems:

Common pitfalls

• Treating guest payments like your software bill. Deposits, balances, ACH/card on bookings, and Quick Pay belong to Payment workflows and reports—not /billing.

• /billing versus /billing-portal. /billing uses a fixed configured portal destination. /billing-portal needs a code from Mallard Bay; they are not interchangeable.

• /account-portal vs /billing. Using the connected-account portal expecting Mallard Bay subscription invoices (or vice versa) leads to confusion. Match the workflow to whether you mean booking payouts or platform subscription.

• Expecting a rich subscription breakdown inside the dashboard shell. After /billing, you typically land on Stripe. In-repo UI that lists subscription tier name, subscription start date, current period boundaries, bundled products/add-ons/promotions is wired for internal Mallard Bay operator views (outfitterSubscriptionInfo modal/content), not surfaced as general outfitter “Billing overview” navigation in this repository.

Related workflows that show up beside subscription concerns

• Paywalls and limits (coupons, team members, gated features): the app may block an action with copy pointing you to upgrade via your account manager—pair that with Request subscription changes or your Mallard Bay contact rather than tweaking Stripe payout settings alone.
• Free-tier upgrade path for operators: internal flows can surface a copiable billing portal URL generated per outfitter (outfitterSubscriptionBillingPortalUrl) so an owner can add a payment method before a paid plan change; that is an operator-assisted pattern in this codebase, not a generic outfitter self-serve screen.
• Billing owner / payout setup: ensure the right person is billing owner and has finished Stripe onboarding so booking revenue routes correctly—this does not replace managing your Mallard Bay subscription through Billing or Mallard Bay support.

Unknown from this repository alone

• The exact Stripe Customer Portal screens and allowed actions (which buttons appear, cancellation rules, invoice history layout) depend on Stripe configuration and Mallard Bay’s Stripe setup—not on this frontend code.
• Whether your deployment links “Billing” in a sidebar or homepage card versus only via 书签 / help links / bookmarks: no outfitter-facing navigation wiring to /billing was found besides the routes themselves; routing may be documented or linked from help content outside this app.
• The specific questions and routing behind /for-guides/subscription-requests live on the public Mallard Bay site, not this dashboard codebase.