Store Account Linking - Internal

# Linked Stores Support Guide

This guide is for Pragma customer-support and onboarding teams. Use it when a merchant has multiple store accounts and wants one Primary Store login to access linked store dashboards.

## What This Feature Does

A merchant can keep every store as a separate Pragma merchant account, but link selected stores under one Primary Store.

After setup:

- Primary Store users log in once and can switch between the Primary Store and its Linked Stores from the dashboard header.

- Linked Store users still log in only to their own store. They do not see other stores.

- Each selected Active Store shows its own orders, reports, settings, billing, wallet, automations, tickets, and store data unless a specific cross-store behavior is documented below.

- Store switching is not impersonation. The logged-in user remains the same; only the Active Store changes.

## Terms

**Primary Store**

The main store account whose users can access linked stores.

**Linked Store**

A separate merchant store account connected to one Primary Store.

**Active Store**

The store currently selected in the dashboard after login or store switch.

**Store Switch**

Changing the Active Store from the dashboard header.

**Effective Channel Config**

For WhatsApp, Email, and SMS workflow sends: use the Active Store's own channel setup if present; otherwise, for Linked Stores only, fall back to the Primary Store's channel setup.

## Important Rules

- New merchant accounts are Primary Stores by default.

- Linking is manual. Do not link stores automatically based on email, phone, Shopify owner, GST, domain, or brand name.

- A Linked Store can have only one Primary Store.

- A Linked Store cannot itself own other Linked Stores.

- A store cannot be linked to itself.

- To move a Linked Store from one Primary Store to another, unlink it first, then link it to the new Primary Store.

- Only internal Pragma staff should link or unlink stores.

- Always add a clear support note while linking or unlinking.

- Verify ownership/approval manually before linking. The system does not enforce legal-owner matching.

- Each store keeps its own billing, wallet, plan, and account status in phase one.

- Store links are not provider-specific. They can be used for Shopify or custom stores.

## Before Setup

Confirm these points before linking:

- Merchant explicitly asked for multi-store linked access.

- Merchant confirmed which store should be Primary.

- Merchant confirmed exact MIDs to link.

- Each store already exists as a merchant account in Pragma.

- Each store has completed normal onboarding requirements.

- You have verified that all stores belong to the same merchant/business group through the usual support process.

- You understand which communication setup they expect:

- own WhatsApp/Email/SMS per store, or

- Primary Store channel setup reused by Linked Stores in workflows.

Do not proceed if there is any ownership doubt. Ask the merchant for confirmation first.

## Setup Steps

1. Open internal merchant dashboard for the Primary Store.

2. Open **Store Links**.

3. Enter the Linked Store MID.

4. Add a support note explaining why this store is being linked.

5. Link the store.

6. Repeat for each Linked Store.

7. Verify the Store Links list shows the correct stores.

8. Ask a Primary Store user to log in and confirm the store switcher appears.

If a merchant has only one accessible store, the switcher will not appear. This is expected.

## What Merchant Users Will See

Primary Store users:

- Log in to the Primary Store by default.

- See a store switcher in the top-right header if they can access more than one store.

- Can switch to linked stores without another login.

- See the selected store name and MID in the header.

- See Active Store data after switching.

Linked Store users:

- Log in to only that Linked Store.

- Do not see the Primary Store or sibling Linked Stores.

- Do not get a store switcher unless they separately have more than one accessible store, which should not happen in phase one.

Fresh login:

- Always starts on the user's home store.

- If a Primary Store user had previously switched to a Linked Store, logging out and logging back in should still open the Primary Store first.

## Data Visibility

Normal dashboard pages are Active Store scoped.

This means:

- Orders page shows orders for the selected store only.

- Reports show selected store only.

- Settings show selected store only.

- Automations list/executions show selected store only.

- Wallet and billing show selected store only.

- Return Center pages show selected store only.

- Staff invited while viewing a Linked Store belong to that Linked Store only.

Do not tell merchants that reports or billing become group-level. They do not in phase one.

## Store Switcher Statuses

The switcher may show status badges such as disabled or blocked states.

Support should check:

- Store account status.

- Store plan/subscription state.

- Whether onboarding is complete.

- Whether the merchant must reconnect or reauthenticate any provider.

If a store is disabled, switching may be blocked or limited. Fix the store account status first.

## Settings Behavior

### Shipping / Courier Settings

Primary Store admins can copy allowed shipping/courier settings from the Primary Store to selected Linked Stores.

Careful points:

- Copy is explicit. It is not live inheritance.

- The Primary Store user must select which Linked Stores to overwrite.

- A copied setting may overwrite a Linked Store's customized setup if selected.

- Confirm before overwriting.

- Support should explain status meanings:

- **Not configured**: Linked Store has no copied setup yet.

- **Same as Primary**: Linked Store matches copied Primary settings.

- **Outdated from Primary**: Primary changed after copy.

- **Customized**: Linked Store changed its own settings after copy.

### WhatsApp / Connect Settings

Do not copy WhatsApp provider secrets across stores from the settings UI.

WhatsApp settings page and Manage Templates page should show only the selected store's own setup/templates.

Workflow editor is different:

- When configuring workflow WhatsApp template actions for a Linked Store, template/config reads can use Effective Channel Config.

- This lets a Linked Store workflow pick templates from the Primary Store if the Linked Store has no own WhatsApp setup.

If a Linked Store should use its own WhatsApp number/templates, configure WhatsApp on that Linked Store.

### Email and SMS

Workflow Email and SMS actions follow the same Effective Channel Config rule:

- Use Linked Store's own setup if present.

- Otherwise use Primary Store setup for workflow sends.

Normal settings pages should still represent the selected store's own setup.

## Workflow / Automation Behavior

For workflow sends from a Linked Store:

- Business event belongs to the Linked Store.

- Automation execution belongs to the Linked Store.

- Conversation/message records belong to the Linked Store.

- Wallet debit belongs to the Linked Store.

- Provider credentials may come from the Primary Store if the Linked Store has no own config.

Product/catalog workflow actions do not fall back to Primary Store. Product data is store-specific and should come from the Active Store only.

If a workflow detail page belongs to another store and the merchant switches stores, the dashboard should redirect to the workflow list instead of loading the wrong workflow.

## Inbox Behavior

Direct inbound WhatsApp messages on a shared Primary Store WhatsApp number are created in the Primary Store in phase one when the intended store cannot be reliably identified.

Replies/status callbacks for messages sent from Linked Store workflows should route back to the original Linked Store when provider message identifiers can identify the original outbound message.

For Primary Store support agents, Inbox customer context may show orders/returns from Primary + Linked Stores. Store names must be shown clearly in the UI when multiple stores are involved.

Linked Store users should not get group-wide access through Inbox.

## Billing

Phase one billing is separate per store.

- Primary Store does not pay for Linked Stores.

- Each store has its own wallet.

- Each store creates its own wallet transactions.

- If a Linked Store wallet is low or disabled, that Linked Store is affected.

- Parent-funded billing is a future TODO, not current behavior.

Do not promise consolidated billing unless product/engineering confirms it has shipped.

## Unlinking Stores

Unlinking is rare. Be careful.

Before unlinking:

- Confirm request from authorized merchant contact.

- Confirm exact Primary Store MID and Linked Store MID.

- Add support note.

- Tell merchant that Primary Store users will lose switcher access to that Linked Store.

- Tell merchant that Linked Store's own users can still log in to that store directly.

After unlinking:

- Ask Primary Store user to refresh or log in again.

- Verify the unlinked store no longer appears in the switcher.

- Verify Linked Store direct login still works.

Do not delete merchant accounts while unlinking. Linking only changes access relationship.

## Audit Trail

The system records link/unlink actions and active-store audit metadata.

Support notes matter. Write notes that answer:

- who requested it

- which MIDs were linked/unlinked

- why this was done

- any merchant confirmation reference

Avoid vague notes like "linked as discussed".

## Troubleshooting

### Store switcher not visible

Check:

- User belongs to Primary Store.

- Primary Store has at least one Linked Store.

- User has access to more than one store.

- User refreshed after link setup.

If user belongs to a Linked Store, no switcher is expected.

### Switching store shows login/json error

Ask user to refresh and try again. If it continues, escalate with:

- user email

- Primary Store MID

- selected Linked Store MID

- current page URL

- timestamp

### Page says selected store is not supported

This means that page/API may not yet be audited for Active Store switching.

Escalate with:

- page URL

- API endpoint if visible

- Primary Store MID

- Active Store MID

- user email

- screenshot

- timestamp

### Wrong store data appears after switch

Escalate immediately. Include:

- page URL

- expected MID

- shown MID/header

- example wrong order/report/template/ticket

- screenshot

- timestamp

### WhatsApp templates appear from Primary Store on settings page

This should not happen. Settings Manage Templates should show only Active Store templates.

Workflow editor may show Primary Store templates for Linked Stores when Effective Channel Config applies.

### Workflow sends fail for Linked Store

Check:

- Linked Store has own channel config, or Primary Store has valid channel config.

- Active Store wallet has balance.

- Linked Store account status is active.

- Template exists in the effective channel source.

- Product/catalog action uses Active Store data, not Primary Store data.

### Inbox customer profile/orders look cross-store

For Primary Store shared-support workflows, order/return lookup may include Primary + Linked Stores. Confirm UI shows store names clearly.

If a Linked Store user sees group-wide data, escalate.

## Support Checklist

Use this checklist for every setup:

- Primary Store MID confirmed.

- Linked Store MID(s) confirmed.

- Merchant approval verified.

- Ownership checked manually.

- Store accounts already onboarded.

- Store account statuses checked.

- Billing expectation explained: separate wallets per store.

- WhatsApp expectation explained: settings own-store, workflows effective fallback.

- Shipping/Courier copy behavior explained if used.

- Support note added.

- Store switcher verified for Primary Store user.

- Linked Store direct login behavior verified if needed.

- Merchant told that unsupported pages should be reported with screenshot and URL.

## Do Not Do

- Do not link stores without merchant approval.

- Do not link a store to multiple Primary Stores.

- Do not create multi-level linked-store chains.

- Do not promise consolidated billing.

- Do not promise group-level reports.

- Do not copy WhatsApp secrets manually between stores.

- Do not unlink or relink without a support note.

- Do not treat Store Switch as logging in as another merchant user.