shopify-setup

jezweb ｜ 商業與營運 ｜ 原文 ｜ MIT

設定 Shopify CLI 驗證與 Admin API token 並驗證連線

---
name: shopify-setup
description: "為商店設定 Shopify CLI 驗證和 Admin API 存取。安裝 CLI、驗證、建立 custom app、儲存 access token、驗證連線。只要使用者想連接 Shopify 商店、設定 Shopify API 存取、安裝 Shopify CLI，或排查 Shopify 驗證 / Admin API token 問題，就用這個 skill。"
compatibility: claude-code-only
---

# Shopify Setup

為商店設定可用的 Shopify CLI 驗證和 Admin API 存取。產出一條驗證過的 API 連線，可以直接拿來管理商品和內容。

## 工作流程

### 步驟 1：檢查前置條件

確認 Shopify CLI 已安裝：

```bash
shopify version
```

沒裝的話：

```bash
npm install -g @shopify/cli
```

### 步驟 2：驗證商店身分

```bash
shopify auth login --store mystore.myshopify.com
```

這會開瀏覽器走 OAuth。使用者必須是店主，或有適當權限的員工。

登入後驗證：

```bash
shopify store info
```

### 步驟 3：建立 Custom App 以取得 API 存取

Custom app 提供穩定的 Admin API access token（不像 CLI session token 會過期）。

**先檢查 app 是否已存在**：問使用者有沒有設定過 custom app。有的話跳到步驟 4。

**如果還沒有 custom app**，引導使用者在瀏覽器裡建立：

1. 前往 `https://{store}.myshopify.com/admin/settings/apps/development`
2. 點 **Create an app**
3. 取個名字（例如 "Claude Code Integration"）
4. 點 **Configure Admin API scopes**
5. 啟用這些 scope（細節看 `references/api-scopes.md`）：
   - `read_products`、`write_products`
   - `read_content`、`write_content`
   - `read_product_listings`
   - `read_inventory`、`write_inventory`
   - `read_files`、`write_files`
6. 點 **Save**，再點 **Install app**
7. 複製 **Admin API access token**（只會顯示一次）

如果使用者希望有人協助操作後台，可以用瀏覽器自動化（Chrome MCP 或 playwright-cli）。

### 步驟 4：儲存 Access Token

安全地存好 token。絕對不要 commit 到 git。

**專案內使用**：建立 `.dev.vars`：

```
SHOPIFY_STORE=mystore.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx
```

確認 `.dev.vars` 在 `.gitignore` 裡。

**跨專案使用**：存在你慣用的 secrets 管理工具（環境變數、1Password CLI 等）。

### 步驟 5：驗證 API 存取

用簡單的 GraphQL 查詢測試連線：

```bash
curl -s https://{store}.myshopify.com/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{"query": "{ shop { name primaryDomain { url } } }"}' | jq .
```

預期回應會包含商店名稱和網域。如果拿到 401，代表 token 無效或過期，要重新建立 app。

### 步驟 6：儲存商店設定

在專案根目錄建立 `shopify.config.json`，讓其他 skill 參考：

```json
{
  "store": "mystore.myshopify.com",
  "apiVersion": "2025-01",
  "tokenSource": ".dev.vars"
}
```

---

## 關鍵模式

### API 版本

一定要指定明確的 API 版本（例如 `2025-01`）。在正式環境用 `unstable` 會無預警壞掉。Shopify 每季會淘汰舊的 API 版本。

### Token 類型

| Token | 格式 | 用途 |
|-------|--------|-----|
| Admin API access token | `shpat_*` | Custom app，穩定、長效 |
| CLI session token | 短效 | 只給 Shopify CLI 指令用 |
| Storefront API token | `shpca_*` | 公開的店面查詢 |

這個 skill 設定的是 **Admin API access token**，管理商品和內容用這個才對。

### Rate Limit

Shopify 用 leaky bucket 限流：
- **REST**：瞬間 40 req/秒，持續 2 req/秒
- **GraphQL**：每秒 1,000 cost points，單次查詢最多 2,000 points

大量操作時，用 `bulkOperationRunQuery` mutation，不要用迴圈。

---

## 參考檔案

- `references/api-scopes.md`：管理商品和內容所需的 Admin API scope

---
name: shopify-setup
description: "Set up Shopify CLI auth and Admin API access for a store. Install CLI, authenticate, create custom app, store access token, verify. Use whenever the user wants to connect to a Shopify store, set up Shopify API access, install Shopify CLI, or troubleshoot Shopify auth / Admin API token issues."
compatibility: claude-code-only
---

# Shopify Setup

Set up working Shopify CLI authentication and Admin API access for a store. Produces a verified API connection ready for product and content management.

## Workflow

### Step 1: Check Prerequisites

Verify the Shopify CLI is installed:

```bash
shopify version
```

If not installed:

```bash
npm install -g @shopify/cli
```

### Step 2: Authenticate with the Store

```bash
shopify auth login --store mystore.myshopify.com
```

This opens a browser for OAuth. The user must be a store owner or staff member with appropriate permissions.

After login, verify:

```bash
shopify store info
```

### Step 3: Create a Custom App for API Access

Custom apps provide stable Admin API access tokens (unlike CLI session tokens which expire).

**Check if an app already exists**: Ask the user if they have a custom app set up. If yes, skip to Step 4.

**If no custom app exists**, guide the user through creation via browser:

1. Navigate to `https://{store}.myshopify.com/admin/settings/apps/development`
2. Click **Create an app**
3. Name it (e.g. "Claude Code Integration")
4. Click **Configure Admin API scopes**
5. Enable these scopes (see `references/api-scopes.md` for details):
   - `read_products`, `write_products`
   - `read_content`, `write_content`
   - `read_product_listings`
   - `read_inventory`, `write_inventory`
   - `read_files`, `write_files`
6. Click **Save** then **Install app**
7. Copy the **Admin API access token** (shown only once)

Use browser automation (Chrome MCP or playwright-cli) if the user prefers assistance navigating the admin.

### Step 4: Store the Access Token

Store the token securely. Never commit it to git.

**For project use** — create `.dev.vars`:

```
SHOPIFY_STORE=mystore.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx
```

Ensure `.dev.vars` is in `.gitignore`.

**For cross-project use** — store in your preferred secrets manager (environment variable, 1Password CLI, etc.).

### Step 5: Verify API Access

Test the connection with a simple GraphQL query:

```bash
curl -s https://{store}.myshopify.com/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{"query": "{ shop { name primaryDomain { url } } }"}' | jq .
```

Expected response includes the shop name and domain. If you get a 401, the token is invalid or expired — recreate the app.

### Step 6: Save Store Config

Create a `shopify.config.json` in the project root for other skills to reference:

```json
{
  "store": "mystore.myshopify.com",
  "apiVersion": "2025-01",
  "tokenSource": ".dev.vars"
}
```

---

## Critical Patterns

### API Version

Always specify an explicit API version (e.g. `2025-01`). Using `unstable` in production will break without warning. Shopify retires API versions quarterly.

### Token Types

| Token | Format | Use |
|-------|--------|-----|
| Admin API access token | `shpat_*` | Custom apps — stable, long-lived |
| CLI session token | Short-lived | Shopify CLI commands only |
| Storefront API token | `shpca_*` | Public storefront queries |

This skill sets up **Admin API access tokens** — the right choice for product and content management.

### Rate Limits

Shopify uses a leaky bucket rate limiter:
- **REST**: 40 requests/second burst, 2/second sustained
- **GraphQL**: 1,000 cost points per second, max 2,000 points per query

For bulk operations, use the `bulkOperationRunQuery` mutation instead of looping.

---

## Reference Files

- `references/api-scopes.md` — Admin API scopes needed for product and content management