IF user wants to integrate external services OR build merchant tools OR charge for features:
→ Build an App (see references/app-development.md)
IF user wants to customize checkout OR add admin UI OR create POS actions OR implement discount rules:
→ Build an Extension (see references/extensions.md)
IF user wants to customize storefront design OR modify product/collection pages:
→ Build a Theme (see references/themes.md)
IF user needs both backend logic AND storefront UI:
→ Build App + Theme Extension combination
Shopify CLI Commands
Install CLI:
npm install -g @shopify/cli@latest
Create and run app:
shopify app init # Create new app
shopify app dev # Start dev server with tunnel
shopify app deploy # Build and upload to Shopify
shopify theme init # Create new theme
shopify theme dev # Start local preview at localhost:9292
shopify theme pull --live # Pull live theme
shopify theme push --development # Push to dev theme
Implement cursor-based pagination with pageInfo.endCursor
Use bulk operations for processing more than 250 items
Handle rate limits with exponential backoff
Security
Store API credentials in environment variables
Always verify webhook HMAC signatures before processing
Validate OAuth state parameter to prevent CSRF
Request minimal access scopes
Use session tokens for embedded apps
Performance
Cache API responses when data doesn't change frequently
Use lazy loading in extensions
Optimize images in themes using img_url filter
Monitor GraphQL query costs via response headers
Troubleshooting
IF you see rate limit errors:
→ Implement exponential backoff retry logic
→ Switch to bulk operations for large datasets
→ Monitor X-Shopify-Shop-Api-Call-Limit header
IF authentication fails:
→ Verify the access token is still valid
→ Check that all required scopes were granted
→ Ensure OAuth flow completed successfully
IF extension is not appearing:
→ Verify the extension target is correct
→ Check that extension is published via shopify app deploy
→ Confirm the app is installed on the test store
IF webhook is not receiving events:
→ Verify the webhook URL is publicly accessible
→ Check HMAC signature validation logic
→ Review webhook logs in Partner Dashboard
IF GraphQL query fails:
→ Validate query against schema (use GraphiQL explorer)
→ Check for deprecated fields in error message
→ Verify you have required access scopes
Reference Files
For detailed implementation guides, read these files:
references/app-development.md - OAuth authentication flow, GraphQL mutations for products/orders/billing, webhook handlers, billing API integration
