name	shopify
description	Guide for implementing Shopify apps, extensions, themes, and integrations using GraphQL/REST APIs, Shopify CLI, Polaris UI, and various extension types (Checkout, Admin, POS). Use when building Shopify apps, implementing checkout extensions, customizing admin interfaces, creating themes with Liquid, or integrating with Shopify's APIs.

Shopify Development

This skill provides comprehensive guidance for building on the Shopify platform, including apps, extensions, themes, and API integrations.

When to Use This Skill

Use this skill when you need to:

Build Shopify apps (public or custom)
Create checkout, admin, or POS UI extensions
Develop themes using Liquid templating
Integrate with Shopify APIs (GraphQL Admin API, REST API, Storefront API)
Implement Shopify Functions (discounts, payments, delivery, validation)
Build headless storefronts with Hydrogen
Configure webhooks and metafields
Use Shopify CLI for development workflows

Core Platform Components

1. Shopify CLI

Installation:

npm install -g @shopify/cli@latest

Essential Commands:

shopify app init - Create new app
shopify app dev - Start local development server
shopify app deploy - Deploy app to Shopify
shopify app generate extension - Add extension to app
shopify theme dev - Preview theme locally
shopify theme pull/push - Sync theme files

For detailed CLI reference, see reference/cli-commands.md

2. GraphQL Admin API (Recommended)

Primary API for new development. Efficient, type-safe, flexible.

Endpoint:

https://{shop-name}.myshopify.com/admin/api/2025-01/graphql.json

Authentication:

headers: {
  'X-Shopify-Access-Token': 'your-access-token',
  'Content-Type': 'application/json'
}

Common Operations:

Query products, orders, customers, inventory
Create/update/delete resources via mutations
Bulk operations for large datasets
Real-time data with subscriptions

For comprehensive GraphQL reference, see reference/graphql-admin-api.md

3. REST Admin API (Maintenance Mode)

Use only for legacy systems. Shopify recommends GraphQL for all new development.

Base URL:

https://{shop-name}.myshopify.com/admin/api/2025-01/{resource}.json

Rate Limits:

Standard: 2 requests/second
Plus: 4 requests/second

4. UI Frameworks

Polaris (React)

Design system for consistent Shopify UI:

npm install @shopify/polaris

Polaris Web Components

Framework-agnostic components:

<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>

Extension Types

Checkout UI Extensions

Customize checkout experience with native-rendered components.

Generate:

shopify app generate extension --type checkout_ui_extension

Configuration: shopify.extension.toml

Common Components: View, BlockStack, InlineLayout, Button, TextField, Checkbox, Banner

For detailed extension reference, see reference/ui-extensions.md

Admin UI Extensions

Extend Shopify admin interface.

Types:

App blocks (embedded in native pages)
App overlays (modal experiences)
Links (product/collection/order pages)

POS Extensions

Customize Point of Sale experience.

Types:

Smart Grid Tiles (quick access actions)
Modals (dialogs and forms)
Cart modifications (custom discounts/line items)

Post-Purchase Extensions

Upsell offers after checkout completion.

Target: purchase.thank-you.block.render

Customer Account UI Extensions

Customize post-purchase account pages.

Targets: Account overview, order status/index

Shopify Functions

Serverless backend customization running on Shopify infrastructure.

Function Types:

Discounts: Cart, product, shipping, order discounts
Payment customization: Hide/rename/reorder payment methods
Delivery customization: Custom shipping options
Order routing: Fulfillment location rules
Validation: Cart and checkout business rules
Fulfillment constraints: Bundle shipping rules

Languages: JavaScript, Rust, AssemblyScript

Generate:

shopify app generate extension --type function

Theme Development

Liquid Templating

Core Concepts:

Objects: {{ product.title }} - Output dynamic content
Filters: {{ product.price | money }} - Transform data
Tags: {% if %} {% for %} {% case %} - Control flow

Common Objects:

product - Product data
collection - Collection data
cart - Shopping cart
customer - Customer account
shop - Store information

Architecture:

Layouts: Base templates
Templates: Page structures
Sections: Reusable content blocks (Online Store 2.0)
Snippets: Smaller components

Development:

shopify theme dev    # Local preview
shopify theme pull   # Download from store
shopify theme push   # Upload to store

Authentication & Security

OAuth 2.0 Flow

For public apps accessing merchant stores:

Redirect merchant to authorization URL
Merchant approves access
Receive authorization code
Exchange code for access token
Store token securely

Access Scopes

Request minimum permissions needed:

read_products - View products
write_products - Modify products
read_orders - View orders
write_orders - Modify orders

Full scope list: https://shopify.dev/api/usage/access-scopes

Session Tokens

For embedded apps in Shopify admin using App Bridge.

Webhooks

Real-time event notifications from Shopify.

Configuration: shopify.app.toml

Common Topics:

orders/create, orders/updated, orders/paid
products/create, products/update, products/delete
customers/create, customers/update
app/uninstalled

GDPR Mandatory Webhooks:

customers/data_request
customers/redact
shop/redact

Metafields

Custom data storage for extending Shopify resources.

Owners: Products, variants, customers, orders, collections, shop

Types: text, number, date, URL, JSON, file_reference

Access: Admin API, Storefront API, Liquid templates

Best Practices

Performance

Use GraphQL instead of REST for efficiency
Request only needed fields in queries
Implement pagination for large datasets
Use bulk operations for batch processing
Respect rate limits (cost-based for GraphQL)

User Experience

Follow Polaris design guidelines
Implement loading states
Provide clear error messages
Support keyboard navigation
Test across devices

Security

Store API credentials securely
Use environment variables for tokens
Implement webhook verification
Follow OAuth best practices
Request minimal access scopes

Code Quality

Use TypeScript for type safety
Write comprehensive error handling
Implement retry logic with exponential backoff
Log errors for debugging
Keep dependencies updated

Testing

Use development stores for testing
Test across different store plans
Verify webhook handling
Test app uninstall flow
Validate GDPR compliance

Development Workflow

Initialize App:
```
shopify app init
```

Configure Access Scopes: Edit shopify.app.toml:

[access_scopes]
scopes = "read_products,write_products"

Start Development Server:
```
shopify app dev
```
Generate Extensions:
```
shopify app generate extension
```
Test in Development Store: Install app on test store
Deploy to Production:
```
shopify app deploy
```

Common Patterns

Fetch Products (GraphQL)

query {
  products(first: 10) {
    edges {
      node {
        id
        title
        handle
        variants(first: 5) {
          edges {
            node {
              id
              price
              inventoryQuantity
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Create Product (GraphQL)

mutation {
  productCreate(input: {
    title: "New Product"
    productType: "Clothing"
    variants: [{
      price: "29.99"
      sku: "SKU123"
    }]
  }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

Checkout Extension (React)

import { useState } from 'react';
import {
  render,
  BlockStack,
  TextField,
  Checkbox,
  useApi
} from '@shopify/ui-extensions-react/checkout';

function Extension() {
  const { extensionPoint } = useApi();
  const [checked, setChecked] = useState(false);

  return (
    <BlockStack>
      <TextField label="Gift Message" />
      <Checkbox checked={checked} onChange={setChecked}>
        This is a gift
      </Checkbox>
    </BlockStack>
  );
}

render('Checkout::Dynamic::Render', () => <Extension />);

Resources

Documentation

Official 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: Built into Shopify admin
Shopify CLI: Development workflow
Partner Dashboard: App management
Development stores: Free testing environments

Learning

Shopify Developer Changelog: API updates and deprecations
Built for Shopify: Quality program for apps
Community forums: Help and discussions

Reference Documentation

This skill includes detailed reference documentation:

GraphQL Admin API Reference - Comprehensive API guide
Shopify CLI Commands - Complete CLI reference
UI Extensions - Extension types and components

Troubleshooting

Common Issues

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 is valid
Check required scopes are granted
Ensure OAuth flow completed correctly

Webhook Not Receiving Events:

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

Extension Not Appearing:

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

Version Management

Shopify uses quarterly API versioning (YYYY-MM format):

Current: 2025-01
Each version supported for 12 months
Test updates before quarterly releases
Use version-specific endpoints

App Distribution

Custom Apps

Single merchant installation, no review required.

Public Apps

App Store listing with Shopify review:

Follow app requirements
Complete Built for Shopify criteria
Define pricing model
Submit for review

Note: This skill covers the Shopify platform as of January 2025. Always refer to official Shopify documentation for the latest updates and API versions.

Install Skill

SKILL.md