t1k:web:commerce:shopify

Field	Value
Module	`commerce`
Version	`1.7.0`
Effort	`high`
Tools	—

Keywords: billing, checkout, ecommerce, GraphQL, Liquid, Polaris, shopify, webhooks

How to invoke

/t1k:web:commerce:shopify
[extension-type] [feature]

Shopify Development

Comprehensive guide for building on Shopify platform: apps, extensions, themes, and API integrations.

Platform Overview

Core Components:

Shopify CLI - Development workflow tool
GraphQL Admin API - Primary API for data operations (recommended)
REST Admin API - Legacy API (maintenance mode)
Polaris UI - Design system for consistent interfaces
Liquid - Template language for themes

Extension Points:

Checkout UI - Customize checkout experience
Admin UI - Extend admin dashboard
POS UI - Point of Sale customization
Customer Account - Post-purchase pages
Theme App Extensions - Embedded theme functionality

Quick Start

Prerequisites

# Install Shopify CLI
npm install -g @shopify/cli@latest

# Verify installation
shopify version

Create New App

# Initialize app
shopify app init

# Start development server
shopify app dev

# Generate extension
shopify app generate extension --type checkout_ui_extension

# Deploy
shopify app deploy

Theme Development

# Initialize theme
shopify theme init

# Start local preview
shopify theme dev

# Pull from store
shopify theme pull --live

# Push to store
shopify theme push --development

Development Workflow

Full development workflow (CLI, themes, deployment, apps): see references/platform-patterns.md.

When to Build What

Build an App When:

Integrating external services
Adding functionality across multiple stores
Building merchant-facing admin tools
Managing store data programmatically
Implementing complex business logic
Charging for functionality

Build an Extension When:

Customizing checkout flow
Adding fields/features to admin pages
Creating POS actions for retail
Implementing discount/payment/shipping rules
Extending customer account pages

Build a Theme When:

Creating custom storefront design
Building unique shopping experiences
Customizing product/collection pages
Implementing brand-specific layouts
Modifying homepage/content pages

Combination Approach:

App + Theme Extension:

App handles backend logic and data
Theme extension provides storefront UI
Example: Product reviews, wishlists, size guides

Essential Patterns

Full essential patterns (GraphQL, Liquid, Metafields, Webhooks): see references/platform-patterns.md.

Best Practices

API Usage:

Prefer GraphQL over REST for new development
Request only needed fields to reduce costs
Implement pagination for large datasets
Use bulk operations for batch processing
Respect rate limits (cost-based for GraphQL)

Security:

Store API credentials in environment variables
Verify webhook signatures
Use OAuth for public apps
Request minimal access scopes
Implement session tokens for embedded apps

Performance:

Cache API responses when appropriate
Optimize images in themes
Minimize Liquid logic complexity
Use async loading for extensions
Monitor query costs in GraphQL

Testing:

Use development stores for testing
Test across different store plans
Verify mobile responsiveness
Check accessibility (keyboard, screen readers)
Validate GDPR compliance

Reference Documentation

Detailed guides for advanced topics:

App Development - OAuth, APIs, webhooks, billing
Extensions - Checkout, Admin, POS, Functions
Themes - Liquid, sections, deployment

Scripts

shopify_init.py - Initialize Shopify projects interactively

python scripts/shopify_init.py

Troubleshooting

Rate Limit Errors:

Monitor X-Shopify-Shop-Api-Call-Limit header
Implement exponential backoff
Use bulk operations for large datasets

Authentication Failures:

Verify access token validity
Check required scopes granted
Ensure OAuth flow completed

Extension Not Appearing:

Verify extension target correct
Check extension published
Ensure app installed on store

Webhook Not Receiving:

Verify webhook URL accessible
Check signature validation
Review logs in Partner Dashboard

Resources

Official Documentation:

Shopify Docs: https://shopify.dev/docs
GraphQL API: https://shopify.dev/docs/api/admin-graphql
Shopify CLI: https://shopify.dev/docs/api/shopify-cli
Polaris: https://polaris.shopify.com

Tools:

GraphiQL Explorer (Admin → Settings → Apps → Develop apps)
Partner Dashboard (app management)
Development stores (free testing)

API Versioning:

Quarterly releases (YYYY-MM format)
Current: 2026-04
12-month support per version
Test before version updates

Note: This skill covers Shopify platform as of June 2026. Refer to official documentation for latest updates.

Gotchas

Storefront API rate limit is bucket-based, NOT request/sec — bursting 50 in 5 sec is fine; sustained 10/sec gets throttled. Implement leaky-bucket client-side.
Webhook close-code retry table — 429 retry with backoff; 4xx (non-429) do NOT retry; 5xx retry up to N times then alert.
Multi-currency cart math drifts on FX update during session — recalculate at checkout, never trust the cart total.
Custom apps and public apps have different OAuth scopes per release — pin app version per environment to avoid silent permission loss.
Metafields have a 64KB cap — bulk product imports without chunking silently truncate.