Option A — Register / Identify App Users (Paying Merchants)

This document is the plan for identifying the users who pay for and use the plugin inside Shopify Admin (merchants and their staff). It covers whether you should add your own login/registration, what user details to capture (name, email, phone), and when to capture them.

Important distinction: These “users” are Shopify Admin users (merchant/staff) who install and pay for the app. This is not about storefront visitors using the chat widget.

Prerequisites: Shopify OAuth install flow working; billing (Phase 5) preferred so there is a “paid” state.

1. Objective

Identify the current app user (merchant/staff) without building a separate auth system.
Capture merchant contact details needed for:
- support,
- billing/invoices,
- future email alerts (low balance, critical notices),
- audit trails (who changed what) (optional later).
Store these details in the database in a structured, editable way.

2. Should you authenticate / register them yourself?

Recommendation: do NOT build separate authentication for merchants. Use Shopify OAuth as the login.

Approach	Pros	Cons
Shopify OAuth only (recommended)	Standard for Shopify apps; no extra passwords; secure; works for embedded admin routes.	By default you identify the shop; identifying the exact staff user may require online sessions.
Add your own login (email/password or magic link)	Works outside Shopify; can support non-Shopify portals.	Duplicates identity; more security burden; higher friction; confusing (“two logins”).
Shopify OAuth + Online sessions (optional later)	Lets you identify the exact staff user (userId/email) for audit trails and per-user permissions.	Slightly more complexity; requires enabling/using online access tokens.

Practical plan:

Primary: Shopify OAuth is your authentication. Each admin request already runs inside Shopify (authenticate.admin(request)).
Capture contact details for support/billing and let merchants edit them.
Optional later: use online sessions to track individual staff users for audit logs and per-user permissions.

3. When should we collect name, email, phone (merchant)?

There are three natural points in the merchant journey.

Point	Description	Pros	Cons
A. Immediately after OAuth install (automatic)	On first successful OAuth (`afterAuth`), fetch shop name/email/phone from Shopify Admin API and store as defaults.	Zero friction; you have baseline data immediately.	Shopify shop email/phone may not be the desired support/billing contact.
B. At Billing / Upgrade (optional prompt)	When upgrading to paid, show/confirm “Billing contact email” (default to shop email).	High intent moment; improves billing email accuracy.	Adds friction to upgrade if you require it.
C. In Settings (editable)	Add “Contact details” in Settings where merchant can set support + billing contacts.	Always available; lets them correct details.	Data may remain blank unless combined with A.

Recommendation: Use A + C.

A (automatic defaults): store shop contact from Shopify during afterAuth.
C (editable): let merchants set the real “Support contact” + “Billing contact”.
Add B only if you truly need a guaranteed billing email at the moment of upgrade.

4. Data model

Store contact info at the shop (tenant) level, and optionally at the staff user level.

4.1 Shop-level contact fields (recommended baseline)

Add these fields to Shop:

Defaults (from Shopify):
- shopName (optional)
- shopEmail (optional)
- shopPhone (optional)
App-configured contacts (merchant editable):
- supportContactName, supportContactEmail, supportContactPhone
- billingContactName, billingContactEmail, billingContactPhone

Why both? Shopify’s shop email/phone might not be who should receive alerts/invoices. Editable fields avoid that mismatch.

4.2 Staff user identity (optional later)

If you need “who changed settings” / audit logs:

Use Shopify online sessions so the session contains userId, firstName, lastName, email, etc.
(Your Prisma schema already has a Session model with these optional fields, which is a good foundation.)
Add a ShopUser table keyed by Shopify userId and shopId to store:
- name/email,
- role flags (account owner / collaborator),
- last seen timestamp,
- optional per-user preferences.

5. Where it happens in the product (recommended flow)

5.1 On install / OAuth (`afterAuth`) — automatic capture

Use the existing afterAuth hook in app/shopify.server.js:

Shopify Admin API query: shop { id name email } (see implementation notes below for API limitation).
Store to the Shop row as default contact fields (shopName, shopEmail). shopPhone is not available from the API in 2025-10.

5.2 Settings — editable contacts

A “Store contact” section exists in Settings (app/routes/app.settings.jsx):

Store name — from Shopify, editable.
Store email — from Shopify (shop owner email), editable.
Store phone — manual entry only (not provided by Admin API in 2025-10).

Optional future: Support contact and Billing contact (name/email/phone) for alerts and billing.

5.3 Billing upgrade — optional confirmation

If you want higher-quality billing contacts:

On Billing page or billing confirm, show a small “Confirm billing email” card.
Default to shop email, allow edits, save to DB.

6. Implementation checklist

Add shop-level contact fields to Shop (shopName, shopEmail, shopPhone in Prisma; defaults from Shopify where possible).
Update afterAuth to fetch and store Shopify shop { id name email } as defaults (phone not in API — see §7).
Update Settings UI to include “Store contact” (name, email, phone) and persist to DB.
(Optional) Add billing upgrade confirmation prompt for billing contact email.
(Optional later) Enable online sessions and add ShopUser table for staff identity and audit logs.
QA (store contact): Install app → verify name/email populated; Settings → edit and save; Store phone entered manually.

7. Summary

Question	Recommendation
Should merchants register/login?	No separate auth. Use Shopify OAuth as the login.
When to collect details?	After OAuth (automatic defaults) + Settings (editable); optionally confirm at Billing upgrade.
What to store?	Support + billing contacts on `Shop` (tenant). Optionally staff user identity later via online sessions.
Who are “users”?	Shopify Admin users (merchant + staff) who install/pay for the app.

8. Implementation notes (current)

What’s implemented:

DB: Shop has shopName, shopEmail, shopPhone (all optional). No separate support/billing contact fields yet.
afterAuth (app/shopify.server.js): Runs shop { id name email } and upserts shopName, shopEmail. Does not set shopPhone (see API limitation below).
Settings (app/routes/app.settings.jsx): “Store contact” card with Store name, Store email, Store phone. All three are saved on “Save settings”. When any of the three is empty, the loader fetches from Shopify and updates the DB (name and email only; phone remains manual).
Lazy-fill: First time a merchant opens Settings with empty store contact, the loader calls the same GraphQL query and fills name/email from Shopify.

Shopify Admin API limitation (2025-10):

The Shop type in GraphQL Admin API 2025-10 does not expose shopAddress (error: “Field ‘shopAddress’ doesn’t exist on type ‘Shop’”). So we cannot fetch store phone or store address from the API. There is no documented read_shop_data-style scope in Shopify’s current access scopes list.
Store phone and any future store address are therefore manual entry only in Settings. The UI explains this in the help text for Store phone.

Next: (optional) billing contact confirmation at upgrade; (optional later) online sessions and staff identity for audit trails.