ecommerce-platform-specialist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify Development Expert

Shopify开发专家

Purpose

用途

Provide comprehensive, accurate guidance for building on Shopify's platform based on 24+ official documentation files. Cover all aspects of app development, theme customization, API integration, checkout extensions, and e-commerce features.

基于24+份官方文档，为Shopify平台开发提供全面、准确的指导，涵盖应用开发、主题定制、API集成、结账扩展及电商功能的所有方面。

Documentation Coverage

文档覆盖范围

Full access to official Shopify documentation (when available):

Location:
```
docs/shopify/
```
Files: 25 markdown files
Coverage: Complete API reference, guides, best practices, and implementation patterns

Note: Documentation must be pulled separately:

bash

pipx install docpull
docpull https://shopify.dev/docs -o .claude/skills/shopify/docs

Major Areas:

GraphQL Admin API (products, orders, customers, inventory)
Storefront API (cart, checkout, customer accounts)
REST Admin API (legacy support)
App development (authentication, webhooks, extensions)
Theme development (Liquid, sections, blocks)
Headless commerce (Hydrogen, Oxygen)
Checkout customization (UI extensions, validation)
Shopify Functions (discounts, delivery, payments)
POS extensions (in-person sales)
Subscriptions and selling plans
Metafields and custom data
Shopify Flow automation
CLI and development tools
Privacy and compliance
Performance optimization

可全面访问官方Shopify文档（如有提供）：

位置：
```
docs/shopify/
```
文件： 25个markdown文件
覆盖内容： 完整的API参考、指南、最佳实践及实现模式

注意： 文档需单独拉取：

bash

pipx install docpull
docpull https://shopify.dev/docs -o .claude/skills/shopify/docs

主要领域：

GraphQL Admin API（商品、订单、客户、库存）
Storefront API（购物车、结账、客户账户）
REST Admin API（旧版支持）
应用开发（身份验证、Webhook、扩展）
主题开发（Liquid、区块、组件）
无头电商（Hydrogen、Oxygen）
结账定制化（UI扩展、验证）
Shopify Functions（折扣、配送、支付）
POS扩展（线下销售）
订阅与销售计划
元字段与自定义数据
Shopify Flow自动化
CLI与开发工具
隐私与合规
性能优化

When to Use

使用场景

Invoke when user mentions:

Platform: Shopify, e-commerce, online store, merchant
APIs: GraphQL, REST, Storefront API, Admin API
Products: product management, collections, variants, inventory
Orders: order processing, fulfillment, shipping
Customers: customer data, accounts, authentication
Checkout: checkout customization, payment methods, delivery options
Themes: Liquid templates, theme development, sections, blocks
Apps: app development, extensions, webhooks, OAuth
Headless: Hydrogen, React, headless commerce, Oxygen
Functions: Shopify Functions, custom logic, discounts
Subscriptions: recurring billing, selling plans, subscriptions
Tools: Shopify CLI, development workflow
POS: point of sale, retail, in-person payments

当用户提及以下内容时调用：

平台： Shopify、电商、在线店铺、商家
API： GraphQL、REST、Storefront API、Admin API
商品： 商品管理、集合、变体、库存
订单： 订单处理、履约、配送
客户： 客户数据、账户、身份验证
结账： 结账定制化、支付方式、配送选项
主题： Liquid模板、主题开发、区块、组件
应用： 应用开发、扩展、Webhook、OAuth
无头： Hydrogen、React、无头电商、Oxygen
函数： Shopify Functions、自定义逻辑、折扣
订阅： 定期计费、销售计划、订阅
工具： Shopify CLI、开发工作流
POS： 销售点、零售、线下支付

How to Use Documentation

如何使用文档

When answering questions:

Search for specific topics:

bash

# Use Grep to find relevant docs
grep -r "checkout" .claude/skills/shopify/docs/ --include="*.md"

Read specific documentation:

bash

# API docs
cat .claude/skills/shopify/docs/shopify/api-admin-graphql.md
cat .claude/skills/shopify/docs/shopify/api-storefront.md

Find implementation guides:

bash

# List all guides
ls .claude/skills/shopify/docs/shopify/

回答问题时：

搜索特定主题：

bash

# 使用Grep查找相关文档
grep -r "checkout" .claude/skills/shopify/docs/ --include="*.md"

阅读特定文档：

bash

# API文档
cat .claude/skills/shopify/docs/shopify/api-admin-graphql.md
cat .claude/skills/shopify/docs/shopify/api-storefront.md

查找实现指南：

bash

# 列出所有指南
ls .claude/skills/shopify/docs/shopify/

Core Authentication

核心身份验证

OAuth 2.0 Flow

OAuth 2.0流程

javascript

// Redirect to Shopify OAuth
const authUrl = `https://${shop}/admin/oauth/authorize?` +
  `client_id=${process.env.SHOPIFY_API_KEY}&` +
  `scope=read_products,write_products&` +
  `redirect_uri=${redirectUri}&` +
  `state=${nonce}`;

// Exchange code for access token
const response = await fetch(
  `https://${shop}/admin/oauth/access_token`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.SHOPIFY_API_KEY,
      client_secret: process.env.SHOPIFY_API_SECRET,
      code
    })
  }
);

const { access_token } = await response.json();

javascript

// 重定向至Shopify OAuth
const authUrl = `https://${shop}/admin/oauth/authorize?` +
  `client_id=${process.env.SHOPIFY_API_KEY}&` +
  `scope=read_products,write_products&` +
  `redirect_uri=${redirectUri}&` +
  `state=${nonce}`;

// 交换代码以获取访问令牌
const response = await fetch(
  `https://${shop}/admin/oauth/access_token`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.SHOPIFY_API_KEY,
      client_secret: process.env.SHOPIFY_API_SECRET,
      code
    })
  }
);

const { access_token } = await response.json();

Session Tokens (Modern Embedded Apps)

会话令牌（现代嵌入式应用）

javascript

import { shopifyApi } from '@shopify/shopify-api';

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET,
  scopes: ['read_products', 'write_products'],
  hostName: process.env.HOST,
  isEmbeddedApp: true,
});

javascript

import { shopifyApi } from '@shopify/shopify-api';

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET,
  scopes: ['read_products', 'write_products'],
  hostName: process.env.HOST,
  isEmbeddedApp: true,
});

GraphQL Admin API

Query Products

查询商品

graphql

query {
  products(first: 10) {
    edges {
      node {
        id
        title
        handle
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
        variants(first: 5) {
          edges {
            node {
              id
              sku
              inventoryQuantity
            }
          }
        }
      }
    }
  }
}

graphql

query {
  products(first: 10) {
    edges {
      node {
        id
        title
        handle
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
        variants(first: 5) {
          edges {
            node {
              id
              sku
              inventoryQuantity
            }
          }
        }
      }
    }
  }
}

Create Product

创建商品

graphql

mutation {
  productCreate(input: {
    title: "New Product"
    vendor: "My Store"
    productType: "Apparel"
    variants: [{
      price: "29.99"
      sku: "PROD-001"
    }]
  }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

graphql

mutation {
  productCreate(input: {
    title: "New Product"
    vendor: "My Store"
    productType: "Apparel"
    variants: [{
      price: "29.99"
      sku: "PROD-001"
    }]
  }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

Fetch Orders

获取订单

graphql

query {
  orders(first: 25, query: "fulfillment_status:unfulfilled") {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          email
        }
        lineItems(first: 10) {
          edges {
            node {
              title
              quantity
            }
          }
        }
      }
    }
  }
}

graphql

query {
  orders(first: 25, query: "fulfillment_status:unfulfilled") {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          email
        }
        lineItems(first: 10) {
          edges {
            node {
              title
              quantity
            }
          }
        }
      }
    }
  }
}

Storefront API

Create Cart

创建购物车

graphql

mutation {
  cartCreate(input: {
    lines: [{
      merchandiseId: "gid://shopify/ProductVariant/123"
      quantity: 1
    }]
  }) {
    cart {
      id
      checkoutUrl
      cost {
        totalAmount {
          amount
          currencyCode
        }
      }
    }
  }
}

graphql

mutation {
  cartCreate(input: {
    lines: [{
      merchandiseId: "gid://shopify/ProductVariant/123"
      quantity: 1
    }]
  }) {
    cart {
      id
      checkoutUrl
      cost {
        totalAmount {
          amount
          currencyCode
        }
      }
    }
  }
}

Update Cart

更新购物车

graphql

mutation {
  cartLinesUpdate(
    cartId: "gid://shopify/Cart/xyz"
    lines: [{
      id: "gid://shopify/CartLine/abc"
      quantity: 2
    }]
  ) {
    cart {
      id
      lines(first: 10) {
        edges {
          node {
            quantity
          }
        }
      }
    }
  }
}

graphql

mutation {
  cartLinesUpdate(
    cartId: "gid://shopify/Cart/xyz"
    lines: [{
      id: "gid://shopify/CartLine/abc"
      quantity: 2
    }]
  ) {
    cart {
      id
      lines(first: 10) {
        edges {
          node {
            quantity
          }
        }
      }
    }
  }
}

Webhooks

Webhook

Setup Webhook

设置Webhook

javascript

// Register webhook via API
const webhook = await shopify.webhooks.register({
  topic: 'ORDERS_CREATE',
  address: 'https://your-app.com/webhooks/orders-create',
  format: 'json'
});

javascript

// 通过API注册Webhook
const webhook = await shopify.webhooks.register({
  topic: 'ORDERS_CREATE',
  address: 'https://your-app.com/webhooks/orders-create',
  format: 'json'
});

Verify Webhook

验证Webhook

javascript

import crypto from 'crypto';

function verifyWebhook(body, hmacHeader, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('base64');

  return hash === hmacHeader;
}

// In webhook handler
app.post('/webhooks/orders-create', async (req, res) => {
  const hmac = req.headers['x-shopify-hmac-sha256'];
  const body = await req.text();

  if (!verifyWebhook(body, hmac, process.env.SHOPIFY_API_SECRET)) {
    return res.status(401).send('Invalid HMAC');
  }

  const order = JSON.parse(body);
  // Process order...

  res.status(200).send('OK');
});

javascript

import crypto from 'crypto';

function verifyWebhook(body, hmacHeader, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('base64');

  return hash === hmacHeader;
}

// 在Webhook处理器中
app.post('/webhooks/orders-create', async (req, res) => {
  const hmac = req.headers['x-shopify-hmac-sha256'];
  const body = await req.text();

  if (!verifyWebhook(body, hmac, process.env.SHOPIFY_API_SECRET)) {
    return res.status(401).send('Invalid HMAC');
  }

  const order = JSON.parse(body);
  // 处理订单...

  res.status(200).send('OK');
});

Liquid Templates

Liquid模板

Basic Liquid

基础Liquid语法

liquid

<!-- Output product title -->
{{ product.title }}

<!-- Conditional logic -->
{% if product.available %}
  <button>Add to Cart</button>
{% else %}
  <span>Sold Out</span>
{% endif %}

<!-- Loop through variants -->
{% for variant in product.variants %}
  <option value="{{ variant.id }}">
    {{ variant.title }} - {{ variant.price | money }}
  </option>
{% endfor %}

liquid

<!-- 输出商品标题 -->
{{ product.title }}

<!-- 条件逻辑 -->
{% if product.available %}
  <button>Add to Cart</button>
{% else %}
  <span>Sold Out</span>
{% endif %}

<!-- 遍历变体 -->
{% for variant in product.variants %}
  <option value="{{ variant.id }}">
    {{ variant.title }} - {{ variant.price | money }}
  </option>
{% endfor %}

Custom Section

自定义区块

liquid

{% schema %}
{
  "name": "Featured Product",
  "settings": [
    {
      "type": "product",
      "id": "product",
      "label": "Product"
    }
  ]
}
{% endschema %}

{% if section.settings.product %}
  {% assign product = section.settings.product %}
  <div class="featured-product">
    <img src="{{ product.featured_image | img_url: '500x' }}" alt="{{ product.title }}">
    <h2>{{ product.title }}</h2>
    <p>{{ product.price | money }}</p>
  </div>
{% endif %}

liquid

{% schema %}
{
  "name": "Featured Product",
  "settings": [
    {
      "type": "product",
      "id": "product",
      "label": "Product"
    }
  ]
}
{% endschema %}

{% if section.settings.product %}
  {% assign product = section.settings.product %}
  <div class="featured-product">
    <img src="{{ product.featured_image | img_url: '500x' }}" alt="{{ product.title }}">
    <h2>{{ product.title }}</h2>
    <p>{{ product.price | money }}</p>
  </div>
{% endif %}

Shopify Functions

Discount Function

折扣函数

javascript

// Function to apply volume discount
export default (input) => {
  const quantity = input.cart.lines.reduce((sum, line) => sum + line.quantity, 0);

  let discountPercentage = 0;
  if (quantity >= 10) discountPercentage = 20;
  else if (quantity >= 5) discountPercentage = 10;

  if (discountPercentage > 0) {
    return {
      discounts: [{
        message: `${discountPercentage}% volume discount`,
        targets: [{
          orderSubtotal: {
            excludedVariantIds: []
          }
        }],
        value: {
          percentage: {
            value: discountPercentage.toString()
          }
        }
      }]
    };
  }

  return { discounts: [] };
};

javascript

// 应用批量折扣的函数
export default (input) => {
  const quantity = input.cart.lines.reduce((sum, line) => sum + line.quantity, 0);

  let discountPercentage = 0;
  if (quantity >= 10) discountPercentage = 20;
  else if (quantity >= 5) discountPercentage = 10;

  if (discountPercentage > 0) {
    return {
      discounts: [{
        message: `${discountPercentage}% volume discount`,
        targets: [{
          orderSubtotal: {
            excludedVariantIds: []
          }
        }],
        value: {
          percentage: {
            value: discountPercentage.toString()
          }
        }
      }]
    };
  }

  return { discounts: [] };
};

Delivery Customization

配送定制化

javascript

// Hide specific delivery options
export default (input) => {
  const operations = [];

  // Hide express shipping for orders under $100
  const cartTotal = parseFloat(input.cart.cost.subtotalAmount.amount);

  if (cartTotal < 100) {
    const expressOptions = input.cart.deliveryGroups[0].deliveryOptions
      .filter(option => option.title.toLowerCase().includes('express'));

    expressOptions.forEach(option => {
      operations.push({
        hide: {
          deliveryOptionHandle: option.handle
        }
      });
    });
  }

  return { operations };
};

javascript

// 隐藏特定配送选项
export default (input) => {
  const operations = [];

  // 订单金额低于100美元时隐藏加急配送
  const cartTotal = parseFloat(input.cart.cost.subtotalAmount.amount);

  if (cartTotal < 100) {
    const expressOptions = input.cart.deliveryGroups[0].deliveryOptions
      .filter(option => option.title.toLowerCase().includes('express'));

    expressOptions.forEach(option => {
      operations.push({
        hide: {
          deliveryOptionHandle: option.handle
        }
      });
    });
  }

  return { operations };
};

Hydrogen (Headless Commerce)

Hydrogen（无头电商）

Product Page

商品页面

typescript

// app/routes/products.$handle.tsx
import {json, LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {useLoaderData} from '@remix-run/react';

export async function loader({params, context}: LoaderFunctionArgs) {
  const {product} = await context.storefront.query(PRODUCT_QUERY, {
    variables: {handle: params.handle},
  });

  return json({product});
}

export default function Product() {
  const {product} = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>{product.title}</h1>
      <img src={product.featuredImage.url} alt={product.title} />
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} />
    </div>
  );
}

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
      featuredImage {
        url
        altText
      }
      variants(first: 10) {
        nodes {
          id
          price {
            amount
            currencyCode
          }
        }
      }
    }
  }
`;

typescript

// app/routes/products.$handle.tsx
import {json, LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {useLoaderData} from '@remix-run/react';

export async function loader({params, context}: LoaderFunctionArgs) {
  const {product} = await context.storefront.query(PRODUCT_QUERY, {
    variables: {handle: params.handle},
  });

  return json({product});
}

export default function Product() {
  const {product} = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>{product.title}</h1>
      <img src={product.featuredImage.url} alt={product.title} />
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} />
    </div>
  );
}

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
      featuredImage {
        url
        altText
      }
      variants(first: 10) {
        nodes {
          id
          price {
            amount
            currencyCode
          }
        }
      }
    }
  }
`;

Shopify CLI

Common Commands

常用命令

bash

undefined

bash

undefined

Create new app

创建新应用

shopify app init

Start development server

启动开发服务器

shopify app dev

Deploy app

部署应用

shopify app deploy

Create extension

创建扩展

shopify app generate extension

Create theme

创建主题

shopify theme init

Serve theme locally

本地预览主题

shopify theme dev --store=your-store.myshopify.com

Push theme

推送主题

shopify theme push

Pull theme

拉取主题

shopify theme pull

undefined

shopify theme pull

undefined

Testing

测试

Test Stores

测试店铺

Create Partner account: https://partners.shopify.com
Create development store
Install your app
Test features

创建合作伙伴账户：https://partners.shopify.com
创建开发店铺
安装你的应用
测试功能

Test Data

测试数据

javascript

// Create test product
const product = await shopify.rest.Product.save({
  session,
  title: "Test Product",
  body_html: "<strong>Test description</strong>",
  vendor: "Test Vendor",
  product_type: "Test Type",
  variants: [{
    price: "19.99",
    sku: "TEST-001"
  }]
});

// Create test order
const order = await shopify.rest.Order.save({
  session,
  line_items: [{
    variant_id: 123456789,
    quantity: 1
  }],
  customer: {
    email: "test@example.com"
  }
});

javascript

// 创建测试商品
const product = await shopify.rest.Product.save({
  session,
  title: "Test Product",
  body_html: "<strong>Test description</strong>",
  vendor: "Test Vendor",
  product_type: "Test Type",
  variants: [{
    price: "19.99",
    sku: "TEST-001"
  }]
});

// 创建测试订单
const order = await shopify.rest.Order.save({
  session,
  line_items: [{
    variant_id: 123456789,
    quantity: 1
  }],
  customer: {
    email: "test@example.com"
  }
});

Security Best Practices

安全最佳实践

API Keys:
- Store in environment variables
- Never commit to version control
- Use separate keys per environment
- Rotate if compromised
Webhooks:
- ALWAYS verify HMAC signatures
- Use HTTPS endpoints only
- Return 200 immediately
- Process async
Access Scopes:
- Request minimal scopes
- Document why each scope is needed
- Review periodically
Rate Limits:
- Respect API rate limits
- Implement exponential backoff
- Monitor API usage

API密钥：
- 存储在环境变量中
- 绝不要提交到版本控制
- 每个环境使用单独的密钥
- 泄露后立即轮换
Webhook：
- 始终验证HMAC签名
- 仅使用HTTPS端点
- 立即返回200状态码
- 异步处理
访问权限：
- 请求最小必要权限
- 记录每个权限的用途
- 定期审核
速率限制：
- 遵守API速率限制
- 实现指数退避机制
- 监控API使用情况

Common Errors

常见错误

API Authentication

API身份验证

```
Invalid access token
```
- Check token is valid and has correct scopes
```
Shop not found
```
- Verify shop domain format
```
Missing access token
```
- Include X-Shopify-Access-Token header

```
Invalid access token
```
- 检查令牌是否有效且拥有正确的权限
```
Shop not found
```
- 验证店铺域名格式
```
Missing access token
```
- 包含X-Shopify-Access-Token请求头

GraphQL Errors

GraphQL错误

```
User errors
```
- Check
```
userErrors
```
field in response
```
Throttled
```
- Reduce request rate
```
Field not found
```
- Verify API version supports field

```
User errors
```
- 检查响应中的
```
userErrors
```
字段
```
Throttled
```
- 降低请求频率
```
Field not found
```
- 验证API版本是否支持该字段

Webhook Issues

Webhook问题

```
Invalid HMAC
```
- Check webhook secret and verification logic
```
Delivery failed
```
- Ensure endpoint returns 200 within timeout
```
Not receiving webhooks
```
- Check webhook registration and endpoint URL

```
Invalid HMAC
```
- 检查Webhook密钥和验证逻辑
```
Delivery failed
```
- 确保端点在超时时间内返回200状态码
```
Not receiving webhooks
```
- 检查Webhook注册和端点URL

Resources

资源

Dashboard: https://partners.shopify.com
Documentation: https://shopify.dev
GraphiQL Admin: https://shopify.dev/docs/apps/tools/graphiql-admin-api
Community: https://community.shopify.com
Status: https://www.shopifystatus.com

仪表盘： https://partners.shopify.com
文档： https://shopify.dev
GraphiQL Admin： https://shopify.dev/docs/apps/tools/graphiql-admin-api
社区： https://community.shopify.com
状态： https://www.shopifystatus.com

Documentation Quick Reference

文档快速参考

Need to find something specific?

bash

undefined

需要查找特定内容？

bash

undefined

Search all docs

搜索所有文档

grep -r "search term" .claude/skills/shopify/docs/

Find specific topics

查找特定主题

ls .claude/skills/shopify/docs/shopify/

Read specific guide

阅读特定指南

cat .claude/skills/shopify/docs/shopify/webhooks.md


**Common doc files:**
- `api-admin-graphql.md` - GraphQL Admin API
- `api-storefront.md` - Storefront API
- `authentication.md` - OAuth and auth flows
- `webhooks.md` - Webhook handling
- `apps.md` - App development
- `themes.md` - Theme development
- `liquid.md` - Liquid reference
- `hydrogen.md` - Headless commerce
- `checkout.md` - Checkout customization
- `functions.md` - Shopify Functions
- `cli.md` - CLI commands

cat .claude/skills/shopify/docs/shopify/webhooks.md


**常见文档文件：**
- `api-admin-graphql.md` - GraphQL Admin API
- `api-storefront.md` - Storefront API
- `authentication.md` - OAuth与认证流程
- `webhooks.md` - Webhook处理
- `apps.md` - 应用开发
- `themes.md` - 主题开发
- `liquid.md` - Liquid参考
- `hydrogen.md` - 无头电商
- `checkout.md` - 结账定制化
- `functions.md` - Shopify Functions
- `cli.md` - CLI命令