New Shop Onboarding

Step-by-step guide for setting up LamaShopi for a new merchant.

Checklist

1. Duplicate Repositories

# Clone and rename for the new project
git clone <theme-repo-url> <shop-name>-theme
git clone <app-repo-url> app.<shop-name>

Update remote origins to point to the new project's repositories. Set up CI/CD for the new deployment.

2. Set Up the Shopify App

1. Open the Shopify Dev Dashboard
2. Create app with a descriptive name (e.g., "LamaShopi -- Shop Name")
3. Create a version with:
   • Scopes: read_products, read_inventory, read_customers, read_locations
   • App Proxy: prefix apps, subpath lamashopi, URL pointing to the production app
   • Webhooks API version: 2025-04
4. Release the version
5. Install the app on the merchant's store
6. Copy Client ID and Client secret

WARNING

The store and app must be in the same Shopify organization.

3. Configure the App

cd app.<shop-name>
composer install && npm install
cp .env.example .env
php artisan key:generate

Edit .env with shop-specific values:

APP_URL=https://app.shop-domain.com
SHOPIFY_SHOP_DOMAIN=shop-name.myshopify.com
SHOPIFY_CLIENT_ID=<from-dev-dashboard>
SHOPIFY_CLIENT_SECRET=<from-dev-dashboard>
DB_DATABASE=lamashopi_shopname

# Enable needed features
SHOPIFY_FEATURE_INVENTORY=true
SHOPIFY_FEATURE_WISHLISTS=true
SHOPIFY_FEATURE_OOS=true
SHOPIFY_FEATURE_STORE_LOCATOR=false
SHOPIFY_FEATURE_FREE_SHIPPING_BAR=false
SHOPIFY_FEATURE_BUNDLES=false

4. Database and Users

php artisan migrate
php artisan user:create admin@agency.com --role=agency --password=<password>

Create shop owner accounts if needed:

php artisan user:create owner@merchant.com --role=shop_owner --password=<password>

5. Register Webhooks

php artisan shopify:register-webhooks
php artisan shopify:list-webhooks  # verify

Configure GDPR compliance webhooks manually in the Dev Dashboard version settings. Set the URL to https://app.shop-domain.com/shopify/webhooks/.

6. Build and Deploy

# App assets
npm run build

# Deploy to production server
# (use your CI/CD pipeline or manual deployment)

7. Production Infrastructure

Ensure the following are running:

• [ ] Queue workers (see Production)
• [ ] Scheduler cron job (see Production)
• [ ] SSL certificate installed
• [ ] Redis running and accessible
• [ ] Horizon dashboard accessible (optional)

8. Theme Setup

cd <shop-name>-theme
npm install

Connect the theme to the App Proxy endpoints. Reference implementations are in the companion app at resources/js/shopify-examples/:

• inventory.js — stock per location
• wishlist.js — wishlist CRUD
• oos-notify.js — OOS subscriptions

Adapt these to the theme's JavaScript setup.

9. Configure Mail

If OOS notifications are enabled:

MAIL_MAILER=postmark
POSTMARK_API_KEY=<key>
MAIL_FROM_ADDRESS=noreply@shop-domain.com

Test the full OOS flow (subscribe, confirm, restock trigger) before go-live.

10. Verify

• [ ] App Proxy responds: visit https://shop-name.myshopify.com/apps/lamashopi/ and check for a valid response
• [ ] Webhooks are registered: php artisan shopify:list-webhooks
• [ ] Admin panel works: visit /agency and log in
• [ ] Feature endpoints work: test each enabled feature's proxy endpoint
• [ ] Queue workers are processing: check Horizon dashboard or php artisan queue:monitor
• [ ] Health check passes: GET /health
• [ ] Theme displays correctly with live data

Post-Launch

• Monitor Horizon for failed jobs in the first few days
• Check Flare for any unhandled exceptions
• Verify webhook delivery in the Shopify Dev Dashboard
• Ensure scheduled tasks are running (webhook:cleanup, data:purge)