shopify-development

Shopify Development Skill

Use this skill when the user asks about:

• Building Shopify apps or extensions
• Creating checkout/admin/POS UI customizations
• Developing themes with Liquid templating
• Integrating with Shopify GraphQL or REST APIs
• Implementing webhooks or billing
• Working with metafields or Shopify Functions

---

ROUTING: What to Build

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

---

Execution and version boundaries

Pin the CLI/API version. Examples are scaffolding sketches, not tested deployed apps. App deployment, theme uploads, fulfillment, billing and data exports require the authorized store, scope and intended effect. Do not retry an ambiguous mutation. The initializer emits partial configuration only, refuses existing project folders, and loads .env files only with SHOPIFY_LOAD_ENV_FILES=1. Prefer CLI-generated projects. Development tunnels expose endpoints externally; use test data.

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

Generate extension:

shopify app generate extension --type checkout_ui_extension
shopify app generate extension --type admin_action
shopify app generate extension --type admin_block
shopify app generate extension --type pos_ui_extension
shopify app generate extension --type function

Theme development:

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

---

Access Scopes

Configure in shopify.app.toml:

[access_scopes]
scopes = "read_products,write_products,read_orders,write_orders,read_customers"

Common scopes:

• read_products, write_products - Product catalog access
• read_orders, write_orders - Order management
• read_customers, write_customers - Customer data
• read_inventory, write_inventory - Stock levels
• read_fulfillments, write_fulfillments - Order fulfillment

---

GraphQL patterns (example API 2026-01)

Query Products

query GetProducts($first: Int!, $query: String) {
  products(first: $first, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        variants(first: 5) {
          edges {
            node {
              id
              price
              inventoryQuantity
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Query Orders

query GetOrders($first: Int!) {
  orders(first: $first) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

Set Metafields

mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
      namespace
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

Variables example:

{
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/123",
      "namespace": "custom",
      "key": "care_instructions",
      "value": "Handle with care",
      "type": "single_line_text_field"
    }
  ]
}

---

Checkout extension example (legacy React API)

This React example targets an older extension API, not 2026-01. Generate a Preact extension with the pinned CLI for current APIs; do not mix React hooks/components with 2026-01 web components. Clear the gift attribute when unchecked and handle change failures before using this sketch.

import {useState, useEffect} from "react";
import {
  reactExtension,
  BlockStack,
  TextField,
  Checkbox,
  useApplyAttributeChange,
} from "@shopify/ui-extensions-react/checkout";

export default reactExtension("purchase.checkout.block.render", () => (
  <GiftMessage />
));

function GiftMessage() {
  const [isGift, setIsGift] = useState(false);
  const [message, setMessage] = useState("");
  const applyAttributeChange = useApplyAttributeChange();

  useEffect(() => {
    if (true) { // Also clear a previously saved message when gift is unchecked
      applyAttributeChange({
        type: "updateAttribute",
        key: "gift_message",
        value: isGift ? message : "",
      });
    }
  }, [isGift, message]);

  return (
    <BlockStack spacing="loose">
      <Checkbox checked={isGift} onChange={setIsGift}>
        This is a gift
      </Checkbox>
      {isGift && (
        <TextField
          label="Gift Message"
          value={message}
          onChange={setMessage}
          multiline={3}
        />
      )}
    </BlockStack>
  );
}

---

Liquid Template Example

{% comment %} Product Card Snippet {% endcomment %}
<div class="product-card">
  <a href="{{ product.url }}">
    {% if product.featured_image %}
      <img
        src="{{ product.featured_image | img_url: 'medium' }}"
        alt="{{ product.title | escape }}"
        loading="lazy"
      >
    {% endif %}
    <h3>{{ product.title }}</h3>
    <p class="price">{{ product.price | money }}</p>
    {% if product.compare_at_price > product.price %}
      <p class="sale-badge">Sale</p>
    {% endif %}
  </a>
</div>

---

Webhook Configuration

In shopify.app.toml:

[webhooks]
api_version = "2026-01"

[[webhooks.subscriptions]]
topics = ["orders/create", "orders/updated"]
uri = "/webhooks/orders"

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products"

# GDPR mandatory webhooks (required for app approval)
[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "/webhooks/privacy"

---

Best Practices

API Usage

• Use GraphQL over REST for new development
• Request only fields you need (reduces query cost)
• 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 in the response extensions.cost object

---

Troubleshooting

IF you see rate limit errors: → Implement exponential backoff retry logic → Switch to bulk operations for large datasets → Inspect GraphQL extensions.cost.throttleStatus; the call-limit header is for REST

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
• references/extensions.md - Checkout UI components, Admin UI extensions, POS extensions, Shopify Functions for discounts/payment/delivery
• references/themes.md - Liquid syntax reference, theme directory structure, sections and snippets, common patterns

---

Scripts

• scripts/shopify_init.py - Interactive project scaffolding. Run: python scripts/shopify_init.py
• scripts/shopify_graphql.py - GraphQL utilities with query templates, pagination, rate limiting. Import: from shopify_graphql import ShopifyGraphQL

---

Official Documentation Links

• Shopify Developer Docs: https://shopify.dev/docs
• GraphQL Admin API Reference: https://shopify.dev/docs/api/admin-graphql
• Shopify CLI Reference: https://shopify.dev/docs/api/shopify-cli
• Polaris Design System: https://polaris.shopify.com

API Version: 2026-01 (quarterly releases, 12-month deprecation window)

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.