Partner Store Onboarding

This guide covers how to onboard a store before the app is approved on the Shopify App Store, using a Custom App token instead of the standard OAuth install flow.

Instructions for the Partner Store (Merchant)

Step 1: Create Your LGS Forge Account

1. Go to lgsforge.com and click Sign Up
2. Sign up with Google or create an account with email/password
3. Note the email you used — you'll send it to us in the final step

Step 2: Enable Custom App Development

1. In your Shopify admin, go to Settings → Apps and sales channels
2. Click Develop apps (top right)
3. Click Allow custom app development and confirm
4. Then enable Allow legacy custom app development — this is required to generate an Admin API access token

Step 3: Create the App

1. Click Create an app
2. Name it: LGS Forge Sync
3. Click Create app

Step 4: Configure API Scopes

1. Click Configure Admin API scopes
2. Search for and check each of the following:
   • write_products
   • read_products
   • write_inventory
   • read_inventory
   • read_publications
   • write_publications
   • read_orders
3. Click Save

Step 5: Install and Get Your Token

1. Click the API credentials tab
2. Click Install app and confirm
3. Under Admin API access token, click Reveal token once
4. Copy the token immediately — it starts with shpat_ and is only shown once

Step 6: Send Us Your Details

Send the following securely (DM, not in a public channel):

• Your shop domain: your-store.myshopify.com
• Access token: shpat_xxxxxxxxxxxx
• Your LGS Forge account email: the email you signed up with in Step 1

We'll link everything on our end and let you know when your store is ready.

Important Notes

• You can revoke this token anytime by deleting the custom app in Settings → Apps
• This token never expires unless you revoke it
• Once our app is officially approved on the Shopify App Store, we'll migrate you to the standard install and you can remove the custom app

---

Instructions for Admins (Setting Up the Partner Store)

Once the merchant has sent you their shop domain, access token, and account email, you can onboard them using either the CLI script or the admin API.

Prerequisites

• The merchant must have already created their LGS Forge account (Step 1 above)
• You need their .myshopify.com domain, shpat_ access token, and account email
• For the CLI script: access to the server environment with MONGODB_URI and ENCRYPTION_KEY set

Option A: CLI Script

# Full onboarding: create store + link to user
node server/scripts/onboardPartnerStore.js their-store.myshopify.com shpat_xxx --user merchant@example.com

The script will:

1. Validate the shop domain format
2. Verify the token works against Shopify's API
3. Encrypt the token and create a store record with isPartner: true
4. Link the store to the user's account

Additional flags

# Update an existing store's token (e.g., if they regenerated it)
node server/scripts/onboardPartnerStore.js their-store.myshopify.com shpat_newtoken --user merchant@example.com --force

# Onboard without linking to a user (link later)
node server/scripts/onboardPartnerStore.js their-store.myshopify.com shpat_xxx

Option B: Admin API

Requires admin authentication (JWT from an admin user account).

curl -X POST https://your-api-url/admin/partner-store \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "their-store.myshopify.com",
    "accessToken": "shpat_xxx",
    "userEmail": "merchant@example.com"
  }'

Response

{
  "success": true,
  "shop": "their-store.myshopify.com",
  "shopName": "Their Store Name",
  "isPartner": true,
  "linkedUser": { "email": "merchant@example.com", "name": "Merchant Name" }
}

What Happens Technically

• A stores document is created with isPartner: true — this bypasses the billing middleware
• The access token is encrypted using the same AES-256-GCM encryption as OAuth tokens
• The user's connectedStores array is updated so they see the store in their dashboard
• All app features (sync, pricing, price updates) work normally via the decrypted token

After Onboarding

1. Let the merchant know their store is connected
2. They can log into the dashboard, select sets, and trigger syncs
3. They will NOT be charged (partner stores bypass billing)
4. Monitor via the admin dashboard or GET /admin/stores

Migrating to Standard Install Later

Once the app is approved on the Shopify App Store:

1. Have the merchant install the app normally through the App Store
2. The OAuth callback will update their existing store record with a new access token
3. Remove the isPartner flag if you want to begin billing:

   # In MongoDB shell or script
   db.stores.updateOne({ shop: "their-store.myshopify.com" }, { $set: { isPartner: false } })

4. The merchant can then delete the Custom App from their Shopify admin

Troubleshooting

Issue	Solution
Token verification fails	Confirm the merchant copied the full token (starts with shpat_). They can only reveal it once — if lost, they must uninstall and reinstall the custom app.
User not found	The merchant must sign up at lgsforge.com first. Re-run with --force --user after they register.
Store already exists	Use --force to update, or check if it's a previously uninstalled store that needs reactivation.
Merchant can't see store in dashboard	Verify the user link — check users collection for connectedStores containing their shop domain.