From c897d31b873611a1c6a42aeea5591f4850c0fe5c Mon Sep 17 00:00:00 2001
From: WellBuilder Admin <admin@wellspr.ing>
Date: Tue, 26 May 2026 16:13:30 +0000
Subject: [PATCH] Add docs/storefront-api.md

---
 docs/storefront-api.md | 84 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 docs/storefront-api.md

diff --git a/docs/storefront-api.md b/docs/storefront-api.md
new file mode 100644
index 0000000..82b09c9
--- /dev/null
+++ b/docs/storefront-api.md
@@ -0,0 +1,84 @@
+# Storefront API Sync
+
+The NotShop bundle uses the Shopify Storefront API to pull your product catalog during migration. It is **public and read-only** — no admin credentials required, cannot modify your Shopify store.
+
+---
+
+## Step 1: Create a Storefront API token
+
+1. Log into Shopify Admin
+2. Go to **Settings → Apps and sales channels → Develop apps**
+3. Create or select a headless app
+4. Under **Configuration → Storefront API access**, enable:
+   - `unauthenticated_read_product_listings`
+   - `unauthenticated_read_product_inventory`
+   - `unauthenticated_read_collection_listings`
+   - `unauthenticated_read_customers`
+   - `unauthenticated_read_checkouts`
+5. Save → Install app → Copy the **Storefront API access token**
+
+---
+
+## Step 2: Add to your environment
+
+In `.env` (or Replit Secrets):
+
+```
+SHOPIFY_STOREFRONT_TOKEN=your_access_token_here
+SHOPIFY_STORE_DOMAIN=yourstore.myshopify.com
+```
+
+---
+
+## Step 3: Run the catalog import
+
+```bash
+npm run catalog:import
+```
+
+### What gets imported
+
+| Data | Stored as |
+|---|---|
+| Products | `products` table |
+| Variants | `product_variants` table |
+| Collections | `collections` table |
+| Product images | `image_url` column (CDN URL reference) |
+| Inventory | `in_stock` boolean |
+
+### What is NOT imported
+
+- Customer purchase history
+- Order history (export from Shopify Admin as CSV before cancellation)
+- Draft orders
+- Cost prices
+
+---
+
+## Step 4: Keep catalog in sync during migration
+
+Re-run `npm run catalog:import` anytime. For real-time sync, register a Shopify webhook:
+
+- Topic: `products/update`
+- URL: `https://yourstore.com/webhooks/shopify/product-updated`
+
+Handler: `server/webhook-bridge.ts`
+
+---
+
+## API endpoint
+
+```
+POST https://{SHOPIFY_STORE_DOMAIN}/api/2024-01/graphql.json
+X-Shopify-Storefront-Access-Token: {SHOPIFY_STOREFRONT_TOKEN}
+```
+
+---
+
+## Troubleshooting
+
+**"Unauthorized"** — Check the token is set correctly and the app is installed.
+
+**Empty product list** — Ensure products are published to the Online Store channel in Shopify Admin.
+
+**Images stop loading after cancellation** — Shopify CDN URLs expire after account closure. Migrate images to Bunny.net or Vultr Object Storage before cancelling. Script: `npm run migrate:images`.