keysat-plans/multi-provider-payment-model.md

# Keysat multi-merchant-profile + multi-provider model

## Context

Today both `btcpay_config` and `zaprite_config` are singleton rows
(`id INTEGER PRIMARY KEY CHECK (id = 1)`), and `SETTING_ACTIVE_PROVIDER`
picks one of the two as the daemon's process-wide active provider. Every
call to `state.payment_provider()` returns that one provider, regardless of
which product is being sold. There's no concept of a "merchant" or "seller"
identity anywhere — every product on a Keysat instance is implicitly being
sold by the same legal entity, through the same payment account, with the
same branding and the same post-purchase landing page.

That model breaks the moment a software author wants to run ONE Keysat
instance for multiple distinct businesses. Concrete example: one operator
sells **Recaps** licenses (settled to a Recaps Zaprite org, branded as
Recaps, buyers redirected to `recaps.cc`) AND **Keysat** licenses (settled
to a Keysat Zaprite org, branded as Keysat, buyers redirected to
`keysat.xyz`). Today's architecture forces both to share one merchant
identity, one provider account, one branding set, one redirect URL.

This plan introduces a **merchant profile** layer that owns business
identity, branding, redirect, optional SMTP, AND a set of payment
providers. Products attach to a merchant profile (not directly to a
provider). The buyer sees the merchant profile's brand at checkout and
picks a payment rail from the providers attached to that profile.

Tier-gating: Creator (free) gets 1 merchant profile. Pro/Patron get N.

## Why this shape, not the simpler "per-product provider override"

An earlier draft of this plan had products carry a nullable
`payment_provider_id` override directly. That worked but conflated two
concerns: **business identity** (who's selling this? what's the brand?
where do buyers land?) and **payment routing** (which Stripe / Bitcoin
account receives the money?). In practice an operator running two
businesses wants every product of business A to share a brand AND a set of
payment accounts AND a redirect; copying those fields onto every product
of that business would be redundant and error-prone.

Merchant profile cleanly separates the two:
- **Profile** = the business identity (brand, redirect, support contact,
  optional SMTP), and the set of payment providers that legally settle TO
  that business.
- **Provider** = the technical credential to a specific payment account
  (BTCPay store + API key, OR Zaprite org + API key). One provider per
  account; a profile can have many providers (e.g. BTCPay for Bitcoin
  AND Zaprite for card).
- **Product** = what's being sold, attached to one profile.

This also makes **buyer-currency routing** (previously a deferred future-
consideration) fall out for free: the buy page shows which payment rails
the product's profile supports, the buyer picks Bitcoin / Lightning /
Card, we route through the right provider.

## Design overview

### Data model

```
merchant_profiles (1) ──────< (N) payment_providers
                  (1) ──────< (N) products
                  (1) ──────< (N) subscriptions  [snapshot on create]
```

- Exactly one `merchant_profiles.is_default = 1` row. Auto-created on
  first boot after upgrade, populated from existing
  `SETTING_OPERATOR_NAME`. New operators get one default profile too.
- Each `payment_provider` belongs to exactly ONE profile
  (`merchant_profile_id NOT NULL`). Providers move with the business.
- Each product has `merchant_profile_id NOT NULL`. Default to the
  default profile.
- Each subscription snapshots BOTH `merchant_profile_id` and
  `payment_provider_id` at creation, so mid-cycle changes to the product
  don't silently redirect existing subs to a different business or rail.

### Buy-page resolution at runtime

1. Buyer hits `/buy/<slug>`.
2. Server loads product → product's merchant profile → profile's attached
   providers.
3. Buy page renders the merchant profile's brand (name, color, support
   link), the product's price/tiers, and a payment-method picker exposing
   every rail the attached providers offer (Lightning, on-chain, card,
   etc.).
4. Buyer picks a rail. The picker resolves to one provider (e.g., "Card"
   → the Zaprite provider attached to this profile).
5. Server calls `state.payment_provider_for(profile_id, rail)` →
   `create_invoice` on that provider.
6. After settle, redirect goes to profile's
   `post_purchase_redirect_url` if set, else Keysat's default
   `/thank-you?invoice_id=…` page.

### Subscription renewal resolution

Renewal worker reads `sub.payment_provider_id` and
`sub.merchant_profile_id` from the subscription snapshot — never re-
resolves from the product. This protects existing buyers from operator
edits.

## Tier gating

- **Creator (free)** — exactly 1 merchant profile. Auto-created on first
  boot; can be edited but not deleted, and the create-profile endpoint
  refuses with 402 + upgrade URL if a Creator already has one.
- **Pro / Patron** — unlimited merchant profiles. Same cap-resolution
  pattern as the existing `unlimited_products` / `unlimited_policies`
  entitlements (`tier::current()` returns the cap; admin endpoint checks
  before insert; the existing tier-cap modal shows the upgrade CTA).

New entitlement string: `unlimited_merchant_profiles`. Master Keysat's
Pro and Patron policies need this added to their entitlement lists; the
master operator's self-license then signs with it baked in.

## Schema (migration 0020)

```sql
PRAGMA foreign_keys = ON;

CREATE TABLE merchant_profiles (
    id                          TEXT PRIMARY KEY,           -- UUID v4
    name                        TEXT NOT NULL,              -- "Recaps", "Keysat"
    legal_name                  TEXT,                       -- optional, for receipts/tax
    support_url                 TEXT,
    support_email               TEXT,
    brand_color                 TEXT,                       -- hex
    post_purchase_redirect_url  TEXT,                       -- NULL = Keysat default /thank-you
    is_default                  INTEGER NOT NULL DEFAULT 0,
    -- Optional per-profile SMTP override. NULL means inherit the
    -- StartOS-level / Keysat-singleton SMTP config. Lets a Pro/Patron
    -- operator running 3 businesses send emails from 3 different
    -- domains/senders WITHOUT having to configure 3 separate StartOS
    -- accounts. Pairs with the keysat-smtp-emails plan.
    smtp_host                   TEXT,
    smtp_port                   INTEGER,
    smtp_username               TEXT,
    smtp_password               TEXT,                       -- encrypted at rest (TBD)
    smtp_from_address           TEXT,
    smtp_from_name              TEXT,
    smtp_use_starttls           INTEGER NOT NULL DEFAULT 1,
    created_at                  TEXT NOT NULL,
    updated_at                  TEXT NOT NULL,
    CHECK (is_default IN (0, 1)),
    CHECK (smtp_use_starttls IN (0, 1))
);
CREATE UNIQUE INDEX idx_merchant_profiles_one_default
    ON merchant_profiles(is_default) WHERE is_default = 1;

CREATE TABLE payment_providers (
    id                  TEXT PRIMARY KEY,                   -- UUID v4
    merchant_profile_id TEXT NOT NULL REFERENCES merchant_profiles(id),
    kind                TEXT NOT NULL,                      -- 'btcpay' | 'zaprite'
    label               TEXT NOT NULL,                      -- "Recaps BTCPay", operator-set
    api_key             TEXT NOT NULL,
    base_url            TEXT NOT NULL,
    webhook_id          TEXT,
    webhook_secret      TEXT,                               -- BTCPay HMAC; NULL for Zaprite
    store_id            TEXT,                               -- BTCPay only
    connected_at        TEXT NOT NULL,
    updated_at          TEXT NOT NULL,
    CHECK (kind IN ('btcpay', 'zaprite'))
);
CREATE INDEX idx_payment_providers_profile ON payment_providers(merchant_profile_id);
-- Within a profile, at most one provider of each kind (avoid the
-- two-BTCPay-providers-same-business confusion):
CREATE UNIQUE INDEX idx_payment_providers_profile_kind
    ON payment_providers(merchant_profile_id, kind);

-- When a merchant profile has two providers that BOTH serve the same
-- payment rail (e.g., Recaps profile has both BTCPay and Zaprite, both
-- of which can settle Lightning), the operator picks a preferred
-- provider per rail here. The buy-page picker uses these preferences to
-- route the buyer's pick to the right provider. Rails a provider serves
-- are inherent to the provider kind (BTCPay → Lightning, OnChain;
-- Zaprite → Card, Lightning, OnChain), so the schema doesn't store
-- per-provider "served_rails" — the trait method `served_rails()`
-- returns that. The preference table only kicks in when there's
-- ambiguity within a profile.
CREATE TABLE merchant_profile_rail_preferences (
    merchant_profile_id TEXT NOT NULL REFERENCES merchant_profiles(id),
    rail                TEXT NOT NULL,                      -- 'lightning' | 'onchain' | 'card'
    payment_provider_id TEXT NOT NULL REFERENCES payment_providers(id),
    PRIMARY KEY (merchant_profile_id, rail),
    CHECK (rail IN ('lightning', 'onchain', 'card'))
);

ALTER TABLE products
    ADD COLUMN merchant_profile_id TEXT
    REFERENCES merchant_profiles(id);
CREATE INDEX idx_products_profile ON products(merchant_profile_id);

ALTER TABLE subscriptions
    ADD COLUMN merchant_profile_id TEXT REFERENCES merchant_profiles(id),
    ADD COLUMN payment_provider_id TEXT REFERENCES payment_providers(id);
CREATE INDEX idx_subs_profile  ON subscriptions(merchant_profile_id);
CREATE INDEX idx_subs_provider ON subscriptions(payment_provider_id);
```

### Migration body (data port)

```sql
-- 1. Create the default merchant profile from existing operator settings.
INSERT INTO merchant_profiles(
    id, name, support_url, support_email, brand_color,
    post_purchase_redirect_url, is_default, created_at, updated_at
)
SELECT lower(hex(randomblob(16))),
       COALESCE((SELECT value FROM settings WHERE key='operator_name'), 'Keysat'),
       NULL, NULL, NULL, NULL,
       1, datetime('now'), datetime('now');

-- 2. Migrate btcpay_config → payment_providers (if present), attached to default.
INSERT INTO payment_providers(
    id, merchant_profile_id, kind, label,
    api_key, base_url, webhook_id, webhook_secret, store_id,
    connected_at, updated_at
)
SELECT lower(hex(randomblob(16))),
       (SELECT id FROM merchant_profiles WHERE is_default = 1),
       'btcpay', 'BTCPay (migrated)',
       api_key, base_url, webhook_id, webhook_secret, store_id,
       connected_at, connected_at
FROM btcpay_config;

-- 3. Same for zaprite_config.
INSERT INTO payment_providers(
    id, merchant_profile_id, kind, label,
    api_key, base_url, webhook_id, webhook_secret, store_id,
    connected_at, updated_at
)
SELECT lower(hex(randomblob(16))),
       (SELECT id FROM merchant_profiles WHERE is_default = 1),
       'zaprite', 'Zaprite (migrated)',
       api_key, base_url, webhook_id, NULL, NULL,
       connected_at, connected_at
FROM zaprite_config;

-- 4. Drop the old singleton tables.
DROP TABLE btcpay_config;
DROP TABLE zaprite_config;
DELETE FROM settings WHERE key = 'active_payment_provider';

-- 5. Backfill products + subscriptions to point at the migrated default.
UPDATE products
   SET merchant_profile_id = (SELECT id FROM merchant_profiles WHERE is_default = 1);
UPDATE subscriptions
   SET merchant_profile_id = (SELECT id FROM merchant_profiles WHERE is_default = 1),
       payment_provider_id = (
           -- Pick whichever provider was attached to the default profile.
           -- If both BTCPay and Zaprite were configured pre-migration,
           -- the active-at-cut one wins (most likely whatever the operator
           -- was actively using). Operators with both providers configured
           -- can re-route any sub via the admin UI after the cut.
           SELECT id FROM payment_providers
           WHERE merchant_profile_id = (SELECT id FROM merchant_profiles WHERE is_default = 1)
             AND kind = COALESCE(
                 (SELECT value FROM settings WHERE key = 'active_payment_provider'),
                 (SELECT kind FROM payment_providers
                  WHERE merchant_profile_id = (SELECT id FROM merchant_profiles WHERE is_default = 1)
                  ORDER BY connected_at ASC LIMIT 1)
             )
       );
```

One-way migration: not reversible without a backup restore. Release
notes flag this for the master operator (you) since you're the only
person running Keysat today — no third-party operators to worry about.

**Post-migration manual step for the master operator**: the existing
Zaprite webhook on your sandbox/prod dashboard is registered at
`https://licensing.keysat.xyz/v1/zaprite/webhook` (no provider id).
After the migration runs, the URL becomes
`/v1/zaprite/webhook/{provider-id}`. Update the webhook URL on the
Zaprite side; or, simpler, the connect-flow re-registers a fresh
webhook with the new URL when the operator next clicks "Reconnect" in
the admin UI. No legacy-URL shim in the router — Keysat isn't in the
wild yet so there are no pre-existing webhooks to preserve.

## Rust changes

**`src/merchant_profiles.rs`** (new):
- `pub struct MerchantProfile` mirroring a row.
- `pub async fn list(pool) -> Vec<MerchantProfile>`,
  `get_by_id`, `get_default`, `create`, `update`, `delete`.
- Tier gate inside `create` — refuses with `AppError::TierCap` (existing
  type that triggers the 402 + upgrade modal) when Creator already has
  one profile.

**`src/payment/mod.rs`**:
- `pub struct PaymentProviderConfig` mirroring a row (now includes
  `merchant_profile_id`).
- `pub fn build_provider(cfg: &PaymentProviderConfig) -> Arc<dyn PaymentProvider>`
  factory dispatching on `kind`.
- `repo::list_providers_for_profile(pool, profile_id)`,
  `repo::get_provider_by_id`, etc.
- Drop `SETTING_ACTIVE_PROVIDER` constant + `read/write_active_provider_preference`.
- Add a "rail" concept. **Rail = the buyer-facing payment method**
  (`enum Rail { Lightning, OnChain, Card }`), not "rail = provider."
  This is the right shape for buyer UX (Card / Lightning / Bitcoin are
  familiar choices; "Pay via Zaprite" isn't).
  - Each provider impl declares which rails it serves via a new trait
    method `fn served_rails(&self) -> Vec<Rail>`. BTCPay returns
    `[Lightning, OnChain]`; Zaprite returns `[Card, Lightning, OnChain]`.
    Rails-per-kind are hardcoded — they don't vary per row.
  - The buy page renders the UNION of rails across the profile's
    attached providers as the payment-method picker.
  - When the buyer picks a rail, the routing layer:
    1. Looks up `merchant_profile_rail_preferences(profile_id, rail)` →
       returns a specific provider id if the operator set a preference.
    2. If no preference is set AND only one provider on the profile
       serves that rail → use it directly.
    3. If no preference is set AND multiple providers serve that rail →
       use the first one by `connected_at` order, AND log a warning
       (the admin UI shows the operator a "Set rail preference for
       this profile" prompt to disambiguate explicitly).

**`src/api/mod.rs` (AppState)**:
- Replace single `payment_provider` accessor with two:
  - `state.merchant_profile_for(product_id) -> MerchantProfile`
  - `state.payment_provider_by_id(provider_id) -> Arc<dyn PaymentProvider>`
- Add a cache `provider_cache: Cache<String, Arc<dyn PaymentProvider>>`
  keyed by provider id; invalidated on connect/disconnect/edit.

**Call sites that switch**:
- `src/api/purchase.rs` — resolve product → profile, then accept a
  rail selection from the request body (or default to "first rail" if
  product has no override), then build the provider; pass
  `merchant_profile_id` AND `payment_provider_id` to subscription create.
- `src/api/upgrade.rs` — derive from license → product → profile; pick
  the same rail the original sub used (snapshot).
- `src/subscriptions.rs` — use `sub.payment_provider_id` snapshot
  (already planned in the prior multi-provider draft); additionally
  use `sub.merchant_profile_id` to load redirect URL / branding for
  the renewal webhook payload.
- `src/tipping.rs`, `src/reconcile.rs` — same pattern.

**`src/api/webhook.rs`** — replace the existing
`/v1/{kind}/webhook` routes with `/v1/{kind}/webhook/{provider_id}`.
The `provider_id` path segment resolves to a specific
`payment_providers` row, the handler validates the payload against
that row's secret and updates the right invoice. No legacy-URL shim
— since Keysat isn't in the wild yet, there's no third-party-operator
webhook config to preserve. The master operator updates their own
Zaprite webhook URL post-migration (see the manual step note in the
migration body above).

**`src/api/btcpay_authorize.rs` and `src/api/zaprite_authorize.rs`** —
connect flows:
- Connect now takes a `merchant_profile_id` query param. Default = the
  default profile if not specified.
- Refuses if a provider of the same kind already exists on that profile
  (the unique index would error; we want a clean 409 with a helpful
  message: "Recaps already has a Zaprite provider — disconnect it first
  or connect to a different profile").
- "Disconnect" deletes the provider row; if it was the last provider on
  the profile AND that profile has active products/subscriptions, the
  admin UI prompt requires picking a replacement before delete.
- New endpoint `POST /v1/admin/merchant-profiles/{id}` CRUD endpoints
  for profile management.

## Subscription snapshot semantics

`subscriptions.merchant_profile_id` AND `subscriptions.payment_provider_id`
are both set on create and never changed by product edits. If the operator
later moves a product to a different merchant profile:

- New purchases on that product create subscriptions tied to the NEW
  profile + provider.
- Existing subscriptions keep renewing through their ORIGINAL profile +
  provider.
- Trade-off: an admin "re-route this subscription" action exists as a
  manual flow (see "Mid-cycle subscription migration" in future
  considerations) — never automatic.

## Admin UI changes (in `web/index.html`)

### Settings → Merchant Profiles (new top-level page)

- List view: table of profiles with name, default badge, attached
  provider kinds (icons for BTCPay / Zaprite), product count, action
  menu (edit, set default, delete).
- "Add Merchant Profile" button: tier-gated. On Creator with 1 profile,
  the button shows the tier-cap upgrade modal instead.
- Profile edit page: form with all the merchant_profile fields. Section
  for "Payment providers" listing attached providers with disconnect/
  reconnect; "Connect BTCPay" and "Connect Zaprite" buttons within the
  profile (which is how the connect flow's `merchant_profile_id` query
  param gets populated). Section for optional per-profile SMTP override
  (collapsed by default; the keysat-smtp-emails plan covers the form
  fields in detail).
- Delete profile: refused if the profile has any active products or
  unsettled subscriptions; otherwise prompts confirm.

### Existing Payment Providers page (rename → drop)

- The current "Payment Providers" section on the Settings page is
  removed; provider config now lives INSIDE each merchant profile's
  edit page. There's no top-level "list all providers across all
  profiles" view — providers are scoped to their profile.

### Product create/edit page

- New "Settle through" picker:
  - "Merchant profile" dropdown — required, defaults to the default
    profile. Lists all profiles the operator has configured.
  - Below it, an info chip showing which payment rails buyers will be
    offered ("Card via Zaprite + Lightning via BTCPay") based on the
    chosen profile's attached providers. If the profile has no
    providers, the operator sees an error: "This merchant profile has
    no payment providers connected — buyers can't pay until you add
    one."

### Buy page (`/buy/<slug>`)

- Brand block at top renders the merchant profile's `name`, optionally
  with `brand_color` accent, and "Sold by {name}" subtitle.
- Existing tier-card UI unchanged except for the payment-method picker:
  the picker renders the union of rails served by the profile's
  attached providers (see "rail concept" in the Rust section). When
  the profile exposes a single rail (e.g., a Bitcoin-only seller with
  just BTCPay → only `Lightning` + `OnChain` available), the picker
  shows those two. When the profile exposes one provider serving one
  rail only, hide the picker entirely.
- After payment, redirect respects profile's
  `post_purchase_redirect_url` if set; falls back to Keysat's default
  thank-you page.

**Zero-providers fallback.** If a product's merchant profile has NO
payment providers connected, the buy page refuses to render the payment
flow and shows a clear "This product isn't available right now —
contact the seller." message instead. No tier card, no Pay button.
The product's `merchant_profile_id` field is still NOT NULL (so
referential integrity holds); the empty-providers state is purely a
runtime UX concern. Same message rendered for any rail mismatch
(e.g., product attached to a profile that only serves Card, but the
buyer's region doesn't support card payments — corner case for later).

## Files modified (estimated)

- `migrations/0020_merchant_profiles.sql` (new)
- `src/merchant_profiles.rs` (new)
- `src/payment/mod.rs` — provider factory + rail concept + profile-aware
  accessors
- `src/payment/btcpay.rs`, `src/payment/zaprite/{client,config,provider}.rs`
  — constructors take row config; declare rails
- `src/api/{purchase,upgrade,webhook,btcpay_authorize,zaprite_authorize,
  merchant_profiles}.rs` — call sites + new CRUD endpoints
- `src/api/mod.rs` (AppState) — provider cache + profile accessors
- `src/db/repo.rs` — profile + provider repo helpers
- `src/subscriptions.rs` — snapshot profile_id + provider_id
- `src/tier.rs` — wire `unlimited_merchant_profiles` entitlement
- `src/tipping.rs`, `src/reconcile.rs` — pass profile context
- `web/index.html` — new Merchant Profiles section + product picker +
  buy-page profile branding + payment-method picker
- `startos/versions/v0.2.0.ts` — bump to `:52` (we're at `:51` as of
  the just-pushed commit `4cde540`), release notes flag the one-way
  migration + Creator tier cap + the post-migration manual webhook
  URL update on the Zaprite side

## Verification

1. **Unit/integration tests**: profile CRUD with tier gating
   (Creator hits cap, Pro/Patron doesn't); subscription snapshot
   stickiness across product moves; provider-by-rail resolution.
2. **Migration test**: copy a production-shape DB (BTCPay singleton +
   one product + one active sub + active_provider setting), run
   migrations, confirm: one default profile exists named per operator,
   one BTCPay provider attached, product points to default profile,
   sub points to both default profile + the migrated BTCPay provider.
3. **Sandbox end-to-end**:
   - On a Pro-tier instance, create two profiles: "Recaps" and "Keysat".
   - Connect a Zaprite sandbox org to Recaps; connect a different
     Zaprite sandbox org to Keysat.
   - Create a Recaps product, attach to Recaps profile. Create a Keysat
     product, attach to Keysat profile.
   - Buy each. Confirm:
     - Recaps purchase shows "Sold by Recaps" branding on buy page,
       redirects to Recaps's `post_purchase_redirect_url`, settles to
       the Recaps Zaprite dashboard, webhook hits
       `/v1/zaprite/webhook/{recaps-provider-id}`.
     - Keysat purchase shows Keysat branding, redirects to Keysat
       thank-you, settles to Keysat Zaprite dashboard.
4. **Multi-rail per profile**:
   - On the Recaps profile, also connect BTCPay (separate provider).
   - Buy the Recaps product again. Buy page now shows "Pay with Card"
     and "Pay with Lightning" picker.
   - Pick card → Zaprite. Pick Lightning → BTCPay. Confirm each settles
     to the correct dashboard.
5. **Creator tier cap**:
   - On a Creator-tier instance, attempt to create a second profile.
   - Expect 402 + upgrade modal pointing at the master Keysat upgrade
     URL.
6. **Master-operator upgrade path** (the only existing install):
   - Your StartOS box at `:51` upgrades to this version. Confirm
     migrations 0020 + run successfully on your existing data:
     one auto-created default profile named per your operator name,
     your existing Zaprite provider attached to it, your existing
     products + subscriptions all linked through.
   - After the upgrade, update your Zaprite webhook URL on the
     Zaprite dashboard to the new
     `/v1/zaprite/webhook/{provider-id}` form (or click "Reconnect
     Zaprite" in the new Merchant Profiles UI to have Keysat
     re-register the webhook with the right URL automatically).

## Sequencing

Single cut (`:52`). Since no operators are running Keysat in the wild
yet, there's no "preserve existing UX during the transition" concern
that would justify splitting into two releases — that was the main
reason an earlier draft proposed a phased approach. With the only
upgrade path being the master operator's own install, shipping the
full data-model + Rust + admin UI together makes the migration story
cleaner: one bump, one set of release notes, one post-migration
checklist (update your own Zaprite webhook URL).

Estimate: 2–3 focused days. The biggest single chunk is the admin UI
work — the new Merchant Profiles page, the per-profile-scoped
provider connect flows, the product-page picker, the buy-page
payment-method picker. The Rust data-model + resolution layer is
straightforward; the migration body is a handful of SELECT-then-
INSERT statements; the route refactor is a small Axum diff.

Suggested execution order within the single cut:
1. Migration 0020 + repo helpers (compiles, no behavior change yet).
2. Build out merchant-profile + provider lookup + AppState accessors;
   port the existing call sites to use the new resolution path.
3. Webhook URL refactor + connect-flow `merchant_profile_id` param.
4. Admin UI: Merchant Profiles page first (CRUD), then product-page
   picker, then buy-page branding + payment-method picker.
5. Tier-gate the create-profile endpoint + bake
   `unlimited_merchant_profiles` into master Keysat's Pro/Patron
   policies.
6. Bump to `:52`, write release notes, end-to-end sandbox test (the
   verification plan above).

## Future considerations — still on the roadmap

The merchant-profile shape makes most of these straight extensions.
Listed roughly in order of "smallest leap from this foundation."

### 1. Buyer-currency routing — natively supported

**What this plan already does.** A profile with multiple providers
already exposes a multi-rail picker on the buy page. Currency
routing is the same shape: buyer picks USD → routes through the
profile's card-capable provider (Zaprite); picks BTC → routes through
Bitcoin-capable (BTCPay). No follow-up work needed beyond the
multi-rail picker.

**What's left for a polish pass.** Currency-aware tier card pricing
(if a product is listed in USD but the buyer picks BTC, show the
sat-equivalent live). Already partly there with the multi-currency
work in v0.1.0:43+; the remaining piece is the buy-page rate
display.

### 2. Per-policy provider — "free tier no payment, paid tiers via Stripe"

**Value.** A product with `Free`, `Pro $5/mo` and `Patron 50000
sats/mo` policies could route the paid policies through different
providers. Free tier has no provider at all (today it falls through
to whichever is configured + a $0 invoice).

**What changes from this plan's foundation.** Add a nullable
`payment_provider_id` to `policies` (a SECOND override). Resolution
order: policy override → product's profile → buyer's rail pick.

**Complexity.** Mostly UI (the policy edit modal gets a "settle
through" picker). Half a day on top of this foundation. Probably
not needed for v1 — the per-profile-multi-provider model handles
most cases.

### 3. Mid-cycle subscription migration — "move my subs to a new merchant"

**Value.** Operator changes payment processors (e.g., switches a
profile's Zaprite org) and wants existing recurring subs to
re-attach to the new provider/profile.

**What changes from this plan's foundation.** New admin endpoint
`POST /v1/admin/subscriptions/{id}/migrate` that updates the sub's
`merchant_profile_id` and/or `payment_provider_id`, drops the
captured `zaprite_payment_profile_id` (which is scoped to the old
org), and either prompts the buyer to re-save their card OR issues a
one-time invoice on the new provider to capture a fresh profile on
settle.

**Complexity.** The data model is trivial — the hard part is the
buyer-communication step. Recommended to defer until a real
operator asks. Half a day for endpoint + UI.

### 4. Auto-failover within a merchant profile

**Value.** A profile has BTCPay primary + Zaprite warm-standby. If
BTCPay's webhook deliveries start failing or its API is
unreachable, Keysat automatically routes the next purchase through
Zaprite without manual intervention.

**What changes.** New `payment_providers.fallback_provider_id`
(nullable FK to another provider on the SAME profile). Purchase
flow tries the primary; on `create_invoice` failure (network, 5xx,
timeout), retries with the fallback. Health-check loop also pings
each provider periodically and records last-known-good status for
admin UI.

**Complexity.** Genuine — failure detection is the hard part. 1–2
days for the naive version, more for proper circuit-breaker logic.
Lower priority because most operators tolerate manual intervention
for brief outages.

### 5. Multi-tenant Keysat boxes — "Keysat as a service"

**Value.** Separate business shape: a SaaS provider runs ONE box
that hosts licensing for many INDEPENDENT operators (each with
their own merchant profiles, products, customers, branding, auth).
Different product than the operator-owned licensing server Keysat
is today.

**What changes.** Almost everything — every table needs a
`tenant_id` (or `operator_id`), auth becomes per-tenant, the admin
UI becomes a tenant-scoped view, etc.

**Recommendation.** Don't plan against this. If the SaaS shape ever
becomes interesting, it's a fork or v2.0 product, not a layered-on
feature. The merchant-profile schema we're building IS however a
useful foundation IF that pivot happens, because per-tenant
billing already maps to per-tenant set-of-merchant-profiles.

---

The merchant-profile foundation we're shipping in this cycle is
deliberately shaped to make 1–3 above straight extensions. 4 is a
different kind of work (failure detection, not data model). 5 is a
different product.

## How this composes with the SMTP / operator-alerts plan

See `./keysat-smtp-emails.md` (companion
plan).

- Per-profile SMTP override fields (in this migration) replace what
  the SMTP plan originally placed on `products`. Email branding is
  business-level, not product-level, so it belongs on
  `merchant_profiles`.
- The SMTP plan's "buyer transactional emails" opt-in becomes a
  per-profile flag (`merchant_profiles.keysat_sends_buyer_emails`)
  rather than per-product. Master Keysat's profile defaults it to
  on; Recaps profile defaults it off (Recaps handles its own buyer
  emails via webhooks).
- The SMTP plan's operator alerts are unchanged — those go to the
  operator personally (StartOS-level email), independent of
  merchant profiles.

Migration order: ship this plan first (merchant_profiles table
exists), then the SMTP plan layers per-profile SMTP + email
settings on top of the new table.