Back to Details

shopify-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopify API Skill

Shopify API 技能指南

This skill allows you to effectively interact with Shopify's ecosystem through its various APIs.
本技能可帮助你通过Shopify的各类API高效与其生态系统进行交互。

API Selection Guide

API选择指南

Choose the right API for your task:
  1. Admin GraphQL API (Preferred): Use for most backend operations. It's the primary API for Shopify, offering more features and efficiency than REST.
  2. Admin REST API: Use for simple resource management if GraphQL is too complex for the specific task or if dealing with legacy systems.
  3. Storefront API: Use for building custom shopping experiences (headless commerce). It is unauthenticated or uses public access tokens.
根据你的任务选择合适的API：
  1. Admin GraphQL API（推荐使用）：适用于大多数后端操作。它是Shopify的核心API，相比REST提供更多功能与更高效率。
  2. Admin REST API：若GraphQL对特定任务而言过于复杂，或需要对接遗留系统，可使用此API进行简单的资源管理。
  3. Storefront API：用于构建自定义购物体验（无头电商）。无需身份验证或使用公开访问令牌。

Authentication

身份验证

Admin API (Custom Apps)

Admin API（自定义应用）

Most internal apps use a custom app access token.
  • Header: 
    X-Shopify-Access-Token: <shpat_...>
  • URL: 
    https://{shop}.myshopify.com/admin/api/{version}/{endpoint}
大多数内部应用使用自定义应用访问令牌。
  • 请求头：
    X-Shopify-Access-Token: <shpat_...>
  • URL：
    https://{shop}.myshopify.com/admin/api/{version}/{endpoint}

OAuth (Public Apps)

OAuth（公开应用）

For apps distributed on the App Store.
  • Header: 
    X-Shopify-Access-Token: <access_token>
  • Flow: Requires an OAuth exchange to get the offline/online token.
适用于在应用商店分发的应用。
  • 请求头：
    X-Shopify-Access-Token: <access_token>
  • 流程：需要通过OAuth交换获取离线/在线令牌。

1. Admin GraphQL API

1. Admin GraphQL API

Endpoint

端点

POST https://{shop}.myshopify.com/admin/api/{version}/graphql.json
POST https://{shop}.myshopify.com/admin/api/{version}/graphql.json

Common Patterns

常见使用模式

Querying Products

查询商品

graphql
query getProducts($first: Int!) {
  products(first: $first) {
    edges {
      node {
        id
        title
        handle
      }
      cursor
    }
    pageInfo {
      hasNextPage
    }
  }
}
graphql
query getProducts($first: Int!) {
  products(first: $first) {
    edges {
      node {
        id
        title
        handle
      }
      cursor
    }
    pageInfo {
      hasNextPage
    }
  }
}

Mutation (Update Product)

变更操作（更新商品）

graphql
mutation productUpdate($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}
graphql
mutation productUpdate($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

Pagination

分页

GraphQL uses cursor-based pagination. Always request 
pageInfo { hasNextPage }
and the 
cursor
of the last edge to fetch the next page using the 
after
argument.
GraphQL使用基于游标的分页。请始终请求
pageInfo { hasNextPage }
以及最后一条edge的
cursor
，以便使用
after
参数获取下一页数据。

2. Admin REST API

2. Admin REST API

Endpoint

端点

https://{shop}.myshopify.com/admin/api/{version}/{resource}.json
https://{shop}.myshopify.com/admin/api/{version}/{resource}.json

Pagination

分页

REST API uses link headers for pagination. Do not use 
page
parameter for most resources; use 
page_info
.
Example Request: 
GET /admin/api/2025-10/products.json?limit=50
Response Header: 
Link: <...page_info=...>; rel="next", <...>; rel="previous"
REST API使用链接头进行分页。对于大多数资源，请勿使用
page
参数；请使用
page_info
。
示例请求： 
GET /admin/api/2025-10/products.json?limit=50
响应头： 
Link: <...page_info=...>; rel="next", <...>; rel="previous"

3. Storefront API

3. Storefront API

Endpoint

端点

POST https://{shop}.myshopify.com/api/{version}/graphql.json
POST https://{shop}.myshopify.com/api/{version}/graphql.json

Authentication

身份验证

  • Header: 
    X-Shopify-Storefront-Access-Token: <public_token>
  • 请求头：
    X-Shopify-Storefront-Access-Token: <public_token>

Example Query

示例查询

graphql
query {
  shop {
    name
  }
  products(first: 5) {
    edges {
      node {
        title
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
      }
    }
  }
}
graphql
query {
  shop {
    name
  }
  products(first: 5) {
    edges {
      node {
        title
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

Rate Limits

请求速率限制

Shopify APIs use a leaky bucket algorithm.
  • REST: 40 requests/bucket, refilled at 2/sec (Standard).
  • GraphQL: Cost-based. 1000 cost points/bucket, refill rate varies (50/sec standard).
Handling: Check 
X-Shopify-Shop-Api-Call-Limit
header (REST) or 
extensions.cost
(GraphQL). Implement exponential backoff for 
429 Too Many Requests
.
Shopify API使用漏桶算法进行速率限制。
  • REST：标准限制为每个桶40次请求，每秒补充2次。
  • GraphQL：基于成本计算。每个桶1000个成本点，补充速率各不相同（标准为每秒50个）。
处理方式：检查
X-Shopify-Shop-Api-Call-Limit
请求头（REST）或
extensions.cost
（GraphQL）。针对
429 请求过多
错误，实现指数退避策略。