Shopify Development Skill

このスキルは、ユーザーが以下について質問する場合に使用してください:

• Shopify アプリまたはエクステンションの構築
• チェックアウト/Admin/POS UI カスタマイズの作成
• Liquid テンプレートを使用したテーマの開発
• Shopify GraphQL または REST API との統合
• webhook または請求の実装
• メタフィールドまたは Shopify Functions の操作

---

ROUTING: 何をビルドするか

ユーザーが外部サービスを統合したい、またはマーチャント向けツールをビルドしたい、または機能に対して課金したい場合: → App をビルド (references/app-development.md を参照)

ユーザーがチェックアウトをカスタマイズしたい、または Admin UI を追加したい、または POS アクションを作成したい、または割引ルールを実装したい場合: → Extension をビルド (references/extensions.md を参照)

ユーザーがストアフロントのデザインをカスタマイズしたい、または商品/コレクションページを変更したい場合: → Theme をビルド (references/themes.md を参照)

ユーザーがバックエンド ロジックとストアフロント UI の両方が必要な場合: → App + Theme Extension の組み合わせをビルド

---

Shopify CLI コマンド

CLI をインストール:

npm install -g @shopify/cli@latest

アプリを作成して実行:

shopify app init          # 新しいアプリを作成
shopify app dev           # トンネル付きで開発サーバーを起動
shopify app deploy        # ビルドして Shopify にアップロード

エクステンションを生成:

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

テーマ開発:

shopify theme init        # 新しいテーマを作成
shopify theme dev         # localhost:9292 でローカルプレビューを起動
shopify theme pull --live # ライブテーマをプル
shopify theme push --development  # 開発テーマにプッシュ

---

アクセススコープ

shopify.app.toml で設定:

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

一般的なスコープ:

• read_products, write_products - 商品カタログへのアクセス
• read_orders, write_orders - 注文管理
• read_customers, write_customers - 顧客データ
• read_inventory, write_inventory - 在庫レベル
• read_fulfillments, write_fulfillments - 注文フルフィルメント

---

GraphQL パターン (API 2026-01 に対して検証済み)

商品をクエリ

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 GetOrders($first: Int!) {
  orders(first: $first) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

メタフィールドを設定

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

変数の例:

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

---

チェックアウト エクステンションの例

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 (isGift && message) {
      applyAttributeChange({
        type: "updateAttribute",
        key: "gift_message",
        value: 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 テンプレートの例

{% 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 設定

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 必須 webhook (アプリ承認に必須)
[webhooks.privacy_compliance]
customer_data_request_url = "/webhooks/gdpr/data-request"
customer_deletion_url = "/webhooks/gdpr/customer-deletion"
shop_deletion_url = "/webhooks/gdpr/shop-deletion"

---

ベストプラクティス

API 使用法

• 新規開発では GraphQL を REST より優先する
• 必要なフィールドのみをリクエスト (クエリコスト削減)
• pageInfo.endCursor を使用したカーソルベースのページネーションを実装
• 250 項目以上の処理には一括操作を使用
• 指数バックオフでレート制限に対応

セキュリティ

• API 認証情報を環境変数に保存
• 処理前に常に webhook HMAC 署名を検証
• OAuth state パラメータを検証して CSRF を防止
• 最小限のアクセススコープをリクエスト
• 埋め込みアプリにはセッショントークンを使用

パフォーマンス

• データが頻繁に変わらない場合は API レスポンスをキャッシュ
• エクステンションで遅延ロードを使用
• テーマで img_url フィルターを使用して画像を最適化
• レスポンスヘッダーを使用して GraphQL クエリコストを監視

---

トラブルシューティング

レート制限エラーが表示される場合: → 指数バックオフの再試行ロジックを実装 → 大規模なデータセットには一括操作に切り替え → X-Shopify-Shop-Api-Call-Limit ヘッダーを監視

認証が失敗する場合: → アクセストークンがまだ有効であることを確認 → すべての必要なスコープが付与されていることを確認 → OAuth フローが正常に完了したことを確認

エクステンションが表示されない場合: → エクステンションのターゲットが正しいことを確認 → shopify app deploy でエクステンションが発行されたことを確認 → アプリがテストストアにインストールされていることを確認

Webhook がイベントを受け取らない場合: → webhook URL がパブリックアクセス可能であることを確認 → HMAC 署名検証ロジックを確認 → Partner Dashboard で webhook ログを確認

GraphQL クエリが失敗する場合: → スキーマに対してクエリを検証 (GraphiQL エクスプローラーを使用) → エラーメッセージで非推奨フィールドを確認 → 必要なアクセススコープがあることを確認

---

リファレンスファイル

詳細な実装ガイドについては、以下のファイルを参照してください:

• references/app-development.md - OAuth 認証フロー、商品/注文/請求の GraphQL ミューテーション、webhook ハンドラー、請求 API 統合
• references/extensions.md - チェックアウト UI コンポーネント、Admin UI エクステンション、POS エクステンション、割引/支払い/配送の Shopify Functions
• references/themes.md - Liquid 構文リファレンス、テーマディレクトリ構造、セクションとスニペット、一般的なパターン

---

スクリプト

• scripts/shopify_init.py - インタラクティブなプロジェクトスカフォルディング。実行: python scripts/shopify_init.py
• scripts/shopify_graphql.py - クエリテンプレート、ページネーション、レート制限を備えた GraphQL ユーティリティ。インポート: from shopify_graphql import ShopifyGraphQL

---

公式ドキュメントリンク

• 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 バージョン: 2026-01 (四半期ごとのリリース、12 ヶ月の非推奨期間)