# Setup_Square.md — Wiring up payments for MAGGie Pro

A step-by-step action guide **for the site owner** to take MAGGie Pro from "static demo" to
"actually taking subscriptions." Written so you can follow it click-by-click.

> ⚠️ **Squarespace UI labels change.** The exact menu names below were accurate at time of writing but
> Squarespace reorganizes its dashboard often. If a label doesn't match, follow the **current Squarespace
> Help docs** for the same concept. This guide explains the *concepts and the order* so you can adapt.

---

## 0) First, clear up the name confusion (read this!)

These sound the same and are constantly confused:

| Name | What it actually is | Role here |
|------|--------------------|-----------|
| **Squarespace** | A website + commerce platform (storefront, products, subscriptions, member areas). | **Our storefront / checkout.** Hosts the products and the subscription checkout pages. |
| **Square** | A separate **payment processor** (card reader company; also online payments). | **Optional payment processor** behind the checkout. |
| **Squarespace Payments** | Squarespace's own built-in processor (powered by Stripe under the hood). | The **default/simplest** processor for a Squarespace store. |

**Key architectural fact:** MAGGie Pro is a **static site hosted on Netlify** — it is *not* hosted on
Squarespace. So we use Squarespace purely as the **commerce/checkout backend** and have the static app
**link out** to Squarespace checkout URLs. After payment, the user is **provisioned access** (see §6).

```
  [ MAGGie Pro static app on Netlify ]  --click "Start trial"-->  [ Squarespace checkout ]
                ^                                                          |
                |------------------ access provisioned <------------------|
                       (member area / license key / allowlist)
```

---

## 1) Recommended pricing (what to build in Squarespace)

These are the numbers already reflected in `pricing.html`. Justification in one line each:

| Tier | Price | Why this number |
|------|-------|-----------------|
| **Free** | $0 forever | Real value with no card. Builds trust and a top-of-funnel; experts can self-qualify before paying. |
| **Pro — monthly** | **$19/mo** | Below the psychological $20 line; ~ "one coffee a week"; competitive with self-paced L&D apps. |
| **Pro — annual** | **$182/yr** (≈ $15.20/mo) | ~20% off monthly ($228) — standard annual discount that improves retention & cash flow. |
| **Pro + Coaching — monthly** | **$49/mo** | Adds human coaching; priced for professionals expensing development; supports the 75/25 coach split. |
| **Pro + Coaching — annual** | **$470/yr** (≈ $39.17/mo) | ~20% off the monthly ($588). |
| **Free trial** | **14 days** on Pro, no charge | Long enough to build a pathway + finish a module or two; short enough to drive a decision. |

> You can adjust, but keep the **annual ≈ 20% off** relationship and the **no-charge 14-day trial** —
> both are baked into the page copy and the no-dark-patterns promise.

---

## 2) Create the Squarespace site & choose a commerce plan

1. Sign up / log in at **squarespace.com** and create a site (you can keep it minimal — it's the
   storefront, not the marketing site).
2. Go to **Settings → Billing → Plans** (or **Billing & Account**) and choose a plan that includes
   **commerce + subscriptions**:
   - Subscriptions (recurring products) require a **Commerce "Advanced"** plan (lower commerce tiers
     support one-time products but **not** recurring subscriptions). Confirm against current Squarespace
     plan comparison.
3. Note the **transaction fee**: on the Commerce **Advanced** plan, Squarespace charges **0%** of its own
   transaction fee (you still pay the **payment processor's** card fees, typically ~2.9% + 30¢).

**Cost notes (verify current):**
- Squarespace Commerce **Advanced**: roughly **$40–$72/mo** depending on monthly vs annual billing.
- Processor card fees: ~**2.9% + $0.30** per transaction (Squarespace Payments / Stripe / Square online).
- Budget those processor fees into the 25% platform fee math for coaching.

---

## 3) Connect a payment processor

Pick **one** (you can start with Squarespace Payments and change later):

- **Squarespace Payments** (recommended to start): **Settings → Payments → Connect Squarespace Payments.**
  Simplest, supports subscriptions, no separate account.
- **Stripe:** **Settings → Payments → Connect Stripe.** Good if you already use Stripe elsewhere.
- **Square:** Squarespace supports **Square** for some configurations (notably in-person/point-of-sale and
  certain regions). For **online recurring subscriptions**, confirm Square is supported for your country in
  the current docs; if not, use Squarespace Payments or Stripe for the subscriptions and reserve Square for
  any in-person sessions.
- **PayPal:** can be added as an additional express option.

> If your priority is "use Square specifically," verify Square + Squarespace **recurring subscription**
> support for your region first. Otherwise Squarespace Payments is the path of least resistance.

---

## 4) Create the subscription products (match the tiers)

In **Selling → Products** (or **Commerce → Inventory**), create **Subscription** products:

1. **Pro (Monthly)** — recurring, **$19**, billing period **monthly**.
2. **Pro (Annual)** — recurring, **$182**, billing period **yearly**.
3. **Pro + Coaching (Monthly)** — recurring, **$49**, billing period **monthly**.
4. **Pro + Coaching (Annual)** — recurring, **$470**, billing period **yearly**.

For each product:
- Set a clear name + description (mirror `pricing.html`).
- (Free tier needs **no product** — it's just the app's default state.)

### Configure the 14-day free trial
- In the subscription product settings, enable a **free trial / trial period = 14 days** if your plan
  exposes it. If the Squarespace subscription product **doesn't** offer a native trial in your plan:
  - **Fallback A:** Use a **100%-off coupon** auto-applied for the first cycle (approximate; not a true
    trial), **or**
  - **Fallback B:** Run the trial **in-app** (the app already gates features locally) and only send users
    to Squarespace checkout when the 14 days elapse. This keeps "no charge during trial" literally true.

---

## 5) Get the checkout URLs and paste them into `pricing.html`

Each product/checkout has a shareable URL. From the product's **Share / link** option (or the store
product page URL), copy the link for each tier.

### ➡️ What to paste where (in `pro/pricing.html`)

The CTAs use a `data-checkout` attribute (and a matching `href`) with an obvious placeholder. There are
**two places** the URLs live:

**a) The static CTA buttons** (search for `YOUR-SITE.squarespace.com`):

```html
<a class="btn btn--primary btn--block checkout-cta"
   data-plan="pro-monthly"
   data-checkout="https://YOUR-SITE.squarespace.com/checkout/pro-monthly"   <!-- ⬅ replace -->
   href="https://YOUR-SITE.squarespace.com/checkout/pro-monthly">           <!-- ⬅ replace -->
```

**b) The `PRICES` object in the page's inline `<script>`** (the monthly/annual toggle swaps these in):

```js
const PRICES = {
  pro:   { monthly: { ..., url: "https://YOUR-SITE.squarespace.com/checkout/pro-monthly" },
           annual:  { ..., url: "https://YOUR-SITE.squarespace.com/checkout/pro-annual" } },
  coach: { monthly: { ..., url: "https://YOUR-SITE.squarespace.com/checkout/pro-coaching-monthly" },
           annual:  { ..., url: "https://YOUR-SITE.squarespace.com/checkout/pro-coaching-annual" } },
};
```

Replace **all four** `url:` values and the **two** static `data-checkout`/`href` placeholders with your
real Squarespace links. That's it — the page does the rest.

> Tip: the page detects the `YOUR-SITE.squarespace.com` placeholder and pops a toast instead of navigating,
> so you'll immediately notice any URL you forgot to replace.

---

## 6) Provision access after payment (the "gating" question — be honest)

Because MAGGie Pro is a **static site**, it cannot *securely* verify a subscription by itself — a static
file can't keep a secret. You have three realistic options, easiest → most robust:

1. **Squarespace Member Areas (recommended, lowest effort).**
   Put the paid experience (or a "members" landing) behind a **Squarespace Member Area** and require login
   there. Squarespace handles the gate. The static MAGGie Pro app can then live as the "free" experience,
   with premium content/links surfaced after the member logs in on the Squarespace side. *Limitation:* the
   gated content effectively lives on/behind Squarespace, not the static app.

2. **License key / email allowlist checked by a Netlify Function (robust, a little code).**
   - On successful payment, Squarespace fires an **order webhook** (or use a Zapier/Make automation) → call
     a **Netlify Function** that records the customer email / issues a signed license key (store in Netlify
     Blobs, a KV, Airtable, etc.).
   - The static app calls a second **Netlify Function** (e.g. `/.netlify/functions/verify`) with the user's
     email or key; the function checks the store and returns entitled/not. The secret stays server-side in
     the function — never in the static JS.
   - This is the proper way to keep "static app + real entitlement." Netlify Functions are serverless, so
     there's still **no server to run**.

3. **Simple email allowlist (demo-grade only, NOT secure).**
   Ship a list the app checks client-side. Trivial to bypass — fine for a private beta, not for real
   revenue. Don't rely on this for paid gating.

> **Honest bottom line:** true paywall gating needs *either* Squarespace Member Areas *or* a small
> serverless function (Netlify Functions). A purely static page cannot enforce entitlements on its own.

---

## 7) Test before launch

- Use the processor's **test mode** (Stripe test cards / Squarespace test order) to run a full
  subscribe → trial → first charge → cancel cycle.
- Verify each `pricing.html` CTA opens the **correct** product and that monthly/annual toggle swaps URLs.
- Confirm the trial reminder email and cancellation flow behave as the copy promises (no surprise charges).
- Re-read `pricing.html` copy so consumer terms match what Squarespace actually does.

---

<a id="partner-referral-fees"></a>

## 7A) Partner referral fees — **WIRE THIS UP** (owner TODO)

> **Remember:** We bill Partners via **Square / Squarespace**, not Stripe.
> Partner (domain expert / referred consultant) commercial flow is **not** the Coach 75/25 split.
> After MAGGie makes a **referral** *and* a **consulting contract** exists, the Partner **inputs a referral fee**
> (amount **not fixed**). Suggested default: **US$50 / month**, recurring **until cancelled**.
> Send billing **reminders 10 days before** the next charge.

### Intended Square / Squarespace workflow (to implement)

1. **Trigger:** Partner marks “referral + contract in place” in a future Partner dashboard (or admin confirms).
2. **Amount:** Partner enters USD amount (default suggestion `$50`; allow edit; do **not** hard-code as the only product price).
3. **Collection (Square):** Create or update a **Square Subscription** (or Squarespace recurring checkout / invoice) charged to the Partner → MAGGie, monthly, until cancelled. Prefer Square Subscriptions API / Customer + Catalog variation with a variable amount, or a per-Partner subscription plan.
4. **Reminders:** Schedule email/notification at **D-10** (10 days before next billing date / invoice).
5. **Cancel / change:** Partner (or admin) can cancel or change amount; surface in Transparency / Partner statement.
6. **Secrets / config (when built):** document Square keys already used for commerce (e.g. `SQUARE_ACCESS_TOKEN`, location id, webhook signature) plus any Partner-specific plan IDs — keep amounts editable, not a single fixed Catalog price.

### Checklist (not done yet)

- [ ] Square API: create/update/cancel Partner referral subscription (variable monthly amount)
- [ ] UI: Partner enters fee after referral + contract
- [ ] D-10 reminder job (Netlify scheduled function or Square invoice/subscription webhooks + email)
- [ ] Terms already describe the policy (`coach-terms.html` §1C); keep Square billing code aligned
- [ ] Stress-test with a Partner lane (e.g. spatial strategy / neuro-architecture)

Copy for Partners lives on `coaches.html` (Partner track) and `coach-onboarding.html`.

---

<a id="partner-identity-verify"></a>

## 7B) Coach / Partner identity verification — **WIRE THIS UP** (owner TODO)

> Prevent spoofing: Coaches and Partners must prove inbox ownership and (recommended) 2FA before going live.

### Intended production workflow

1. **Email magic link / OTP** — Netlify Function sends one-time code or signed URL to the onboarding email; mark `identity.emailVerified` only after success.
2. **Domain match** — if `email` domain aligns with practice `website` host, record `identity.domainMatch` (soft signal, not sole proof).
3. **2FA** — after email verify, enroll TOTP (or SMS) for Partner/Coach portal; require second factor for asset edits, payout, and referral-fee entry.
4. **Alternates** — LinkedIn OAuth / OIDC to prove control of the claimed profile; optional DNS TXT / file on their site; manual video check for edge cases.
5. **Ops hold** — do not enable referrals until `identity.emailVerified` + anti-spoof attestation; revoke on suspected impersonation.

### Checklist

- [ ] `/api/partner-verify-send` + `/api/partner-verify-confirm` (email OTP / magic link)
- [ ] Optional LinkedIn OAuth / OIDC
- [ ] TOTP 2FA enrollment for Partner/Coach portal
- [ ] Admin flag for manual identity review
- [ ] Align with `coach-terms.html` §2A and `coach-onboarding.html` Step 5

---

## 8) Quick checklist

- [ ] Squarespace site created; **Commerce Advanced** (subscriptions) plan active.
- [ ] Payment processor connected (**Square** preferred for MAGGie Pro Partner fees; confirm recurring support for your region).
- [ ] 4 subscription products created at the recommended prices.
- [ ] 14-day trial configured (native, coupon fallback, or in-app).
- [ ] 6 placeholder URLs replaced in `pricing.html` (2 static `data-checkout`/`href` + 4 in `PRICES`).
- [ ] Access provisioning chosen (Member Areas **or** Netlify Function entitlement).
- [ ] End-to-end test in processor test mode.
- [ ] Consumer terms / refund policy published and linked.
- [ ] **Partner referral fees** (variable monthly until cancelled + D-10 reminders) — see §7A
- [ ] **Coach/Partner identity verify** (email OTP/magic link + 2FA) — see §7B
- [ ] **Square Calendar, coach directory, PDF proof reuse** — see [`WIRING_TODO.md`](./WIRING_TODO.md)
- [ ] **Site security hardening** — anti-injection, anti-DoS, **anti-scraping/robots/IP**, CSP/headers — see [`SITE_SECURITY_TODO.md`](./SITE_SECURITY_TODO.md)

---

### Related files
- `pricing.html` — the page whose CTAs you wire up here.
- `coaches.html` / `coach-onboarding.html` / `coach-terms.html` — Coach vs Partner tracks; Coach revenue uses the **75% coach / 25% platform** split; Partner referral fees use **Square** (§7A).
- `Setup_Stripe.md` — legacy/alternate notes; **Partner referral fees are Square**, not Stripe.
- [`WIRING_TODO.md`](./WIRING_TODO.md) — Square Calendar, approved-coach directory (firstName + timezone/location), onboarding proof reuse, LinkedIn PDF → dimensions.