Shopify Admin API

# Shopify Admin API

## 简介

对 Shopify Admin REST API 的完全读写权限，用于管理订单、产品、客户、库存、发货、退款、退货和交易。

## 设置

### 环境变量

- `SHOPIFY_STORE_DOMAIN` - 您商店的 myshopify.com 域名（例如 `my-store.myshopify.com`） - `SHOPIFY_ACCESS_TOKEN` - 来自自定义应用的 Admin API 访问令牌

### 所需的 API 权限范围

| 权限范围 | 访问权限 | |-------|--------| | `read_orders` / `write_orders` | 订单、发货、弃单 | | `read_products` / `write_products` | 产品、变体、产品系列 | | `read_customers` / `write_customers` | 客户、细分 | | `read_inventory` / `write_inventory` | 库存级别、商品 | | `read_returns` / `write_returns` | 退货 | | `read_all_orders` | 超过 60 天的订单（需要审批） |

### 身份验证

所有请求都需要此请求头：

``` X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN ```

### 获取访问令牌

1. 前往您的 Shopify Admin > Settings > Apps and sales channels（设置 > 应用和销售渠道） 2. 点击“Develop apps”（开发应用）> “Create an app”（创建应用） 3. 根据您的需要配置 Admin API 权限范围 4. 将应用安装到您的商店 5. 复制 Admin API 访问令牌

## API 参考

基础 URL：`https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10`

### 订单

#### 列出订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

查询参数：`ids`、`limit`、`since_id`、`created_at_min`、`created_at_max`、`updated_at_min`、`updated_at_max`、`processed_at_min`、`processed_at_max`、`status`（open、closed、cancelled、any）、`financial_status`、`fulfillment_status`、`fields`

#### 获取订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取订单数量

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/count.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 更新订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X PUT \ -d '{"order":{"id":{ORDER_ID},"note":"Updated note","tags":"priority,vip"}}' ```

#### 关闭订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/close.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X POST ```

#### 重新打开订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/open.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X POST ```

#### 取消订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/cancel.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"reason":"customer","email":true,"restock":true}' ```

取消原因：`customer`、`fraud`、`inventory`、`declined`、`other`

### 产品

#### 列出产品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

查询参数：`ids`、`limit`、`since_id`、`title`、`vendor`、`handle`、`product_type`、`collection_id`、`created_at_min`、`created_at_max`、`updated_at_min`、`updated_at_max`、`published_at_min`、`published_at_max`、`published_status`（published、unpublished、any）、`fields`、`status`（active、archived、draft）

#### 获取产品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products/{PRODUCT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取产品数量

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products/count.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建产品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"product":{"title":"Burton Custom Freestyle","body_html":"<strong>Good snowboard!</strong>","vendor":"Burton","product_type":"Snowboard","status":"draft","variants":[{"price":"99.99","sku":"BOARD-001"}]}}' ```

#### 更新产品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products/{PRODUCT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X PUT \ -d '{"product":{"id":{PRODUCT_ID},"title":"Updated Product Title","status":"active"}}' ```

#### 删除产品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products/{PRODUCT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X DELETE ```

### 产品变体

#### 列出产品的变体

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products/{PRODUCT_ID}/variants.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取变体

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/variants/{VARIANT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建变体

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products/{PRODUCT_ID}/variants.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"variant":{"option1":"Blue","price":"19.99","sku":"BLUE-001","inventory_management":"shopify"}}' ```

#### 更新变体

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/variants/{VARIANT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X PUT \ -d '{"variant":{"id":{VARIANT_ID},"price":"24.99","compare_at_price":"29.99"}}' ```

#### 删除变体

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products/{PRODUCT_ID}/variants/{VARIANT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X DELETE ```

### 客户

#### 列出客户

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

查询参数：`ids`、`limit`、`since_id`、`created_at_min`、`created_at_max`、`updated_at_min`、`updated_at_max`、`fields`

#### 搜索客户

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers/search.json?query=email:[email protected]" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

搜索字段：`email`、`phone`、`first_name`、`last_name`、`company`、`orders_count`、`total_spent`、`country`、`state`

#### 获取客户

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers/{CUSTOMER_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取客户数量

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers/count.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建客户

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"customer":{"first_name":"John","last_name":"Doe","email":"[email protected]","phone":"+15551234567","addresses":[{"address1":"123 Main St","city":"Ottawa","province":"ON","country":"CA","zip":"K1A 0B1"}]}}' ```

#### 更新客户

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers/{CUSTOMER_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X PUT \ -d '{"customer":{"id":{CUSTOMER_ID},"tags":"vip,wholesale","note":"Important customer"}}' ```

#### 删除客户

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers/{CUSTOMER_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X DELETE ```

#### 获取客户订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/customers/{CUSTOMER_ID}/orders.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

### 库存

#### 列出库存级别

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/inventory_levels.json?inventory_item_ids={ITEM_ID}" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

查询参数：`inventory_item_ids`（必需）、`location_ids`、`limit`、`updated_at_min`

#### 调整库存级别

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/inventory_levels/adjust.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"location_id":{LOCATION_ID},"inventory_item_id":{ITEM_ID},"available_adjustment":5}' ```

#### 设置库存级别

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/inventory_levels/set.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"location_id":{LOCATION_ID},"inventory_item_id":{ITEM_ID},"available":100}' ```

#### 将库存关联到地点

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/inventory_levels/connect.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"location_id":{LOCATION_ID},"inventory_item_id":{ITEM_ID}}' ```

### 库存商品

#### 列出库存商品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/inventory_items.json?ids={ITEM_IDS}" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取库存商品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/inventory_items/{ITEM_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 更新库存商品

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/inventory_items/{ITEM_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X PUT \ -d '{"inventory_item":{"id":{ITEM_ID},"cost":"25.00","tracked":true}}' ```

### 地点

#### 列出地点

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/locations.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取地点

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/locations/{LOCATION_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取地点数量

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/locations/count.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取地点的库存级别

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/locations/{LOCATION_ID}/inventory_levels.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

### 发货

#### 列出订单的发货

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/fulfillments.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取发货

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/fulfillments/{FULFILLMENT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取发货数量

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/fulfillments/count.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建发货

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/fulfillments.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"fulfillment":{"line_items_by_fulfillment_order":[{"fulfillment_order_id":{FULFILLMENT_ORDER_ID}}],"tracking_info":{"number":"1Z999AA10123456784","url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","company":"UPS"}}}' ```

#### 更新物流跟踪

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/fulfillments/{FULFILLMENT_ID}/update_tracking.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"fulfillment":{"tracking_info":{"number":"1Z999AA10123456784","url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","company":"UPS"},"notify_customer":true}}' ```

#### 取消发货

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/fulfillments/{FULFILLMENT_ID}/cancel.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X POST ```

### 发货订单

#### 列出订单的发货订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/fulfillment_orders.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取发货订单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/fulfillment_orders/{FULFILLMENT_ORDER_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

### 退款

#### 列出订单的退款

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/refunds.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取退款

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/refunds/{REFUND_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 计算退款

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/refunds/calculate.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"refund":{"shipping":{"full_refund":true},"refund_line_items":[{"line_item_id":{LINE_ITEM_ID},"quantity":1,"restock_type":"return"}]}}' ```

重新入库类型：`no_restock`、`cancel`、`return`、`legacy_restock`

#### 创建退款

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/refunds.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"refund":{"currency":"USD","notify":true,"note":"Customer returned item","shipping":{"full_refund":true},"refund_line_items":[{"line_item_id":{LINE_ITEM_ID},"quantity":1,"restock_type":"return"}],"transactions":[{"parent_id":{TRANSACTION_ID},"amount":"10.00","kind":"refund","gateway":"shopify_payments"}]}}' ```

### 退货

#### 列出退货

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/returns.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

查询参数：`limit`、`status`（open、closed、cancelled、requested、in_progress）

#### 获取退货

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/returns/{RETURN_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建退货

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/returns.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"return":{"order_id":{ORDER_ID},"return_line_items":[{"fulfillment_line_item_id":{FULFILLMENT_LINE_ITEM_ID},"quantity":1,"return_reason":"WRONG_ITEM"}]}}' ```

退货原因：`UNKNOWN`、`SIZE_TOO_SMALL`、`SIZE_TOO_LARGE`、`UNWANTED`、`NOT_AS_DESCRIBED`、`WRONG_ITEM`、`DEFECTIVE`、`STYLE`、`COLOR`、`OTHER`

### 交易

#### 列出订单的交易

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/transactions.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取交易

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/transactions/{TRANSACTION_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取交易数量

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/transactions/count.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建交易（捕获）

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/orders/{ORDER_ID}/transactions.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"transaction":{"kind":"capture","amount":"10.00","parent_id":{AUTHORIZATION_ID}}}' ```

交易类型：`authorization`、`capture`、`sale`、`void`、`refund`

### 产品系列

#### 列出自定义产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/custom_collections.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取自定义产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/custom_collections/{COLLECTION_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建自定义产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/custom_collections.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"custom_collection":{"title":"Summer Collection","body_html":"<p>Summer products</p>"}}' ```

#### 更新自定义产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/custom_collections/{COLLECTION_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X PUT \ -d '{"custom_collection":{"id":{COLLECTION_ID},"title":"Updated Collection"}}' ```

#### 删除自定义产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/custom_collections/{COLLECTION_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X DELETE ```

#### 列出智能产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/smart_collections.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 获取智能产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/smart_collections/{COLLECTION_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

#### 创建智能产品系列

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/smart_collections.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"smart_collection":{"title":"Sale Items","rules":[{"column":"compare_at_price","relation":"greater_than","condition":"0"}]}}' ```

规则字段：`title`、`type`、`vendor`、`variant_price`、`tag`、`compare_at_price`、`weight`、`inventory_stock`、`variant_compare_at_price`、`variant_weight`、`variant_inventory`、`variant_title`

规则关系：`equals`、`not_equals`、`greater_than`、`less_than`、`starts_with`、`ends_with`、`contains`、`not_contains`

### 产品收集（产品-产品系列关联）

#### 列出产品收集

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/collects.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

查询参数：`product_id`、`collection_id`、`limit`、`since_id`、`fields`

#### 创建产品收集

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/collects.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"collect":{"product_id":{PRODUCT_ID},"collection_id":{COLLECTION_ID}}}' ```

#### 删除产品收集

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/collects/{COLLECT_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X DELETE ```

### 弃单

#### 列出弃单

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/checkouts.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

查询参数：`limit`、`since_id`、`created_at_min`、`created_at_max`、`updated_at_min`、`updated_at_max`、`status`（open、closed）

#### 获取弃单数量

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/checkouts/count.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

## 状态参考

### 订单状态

| 字段 | 值 | |-------|--------| | `financial_status` | pending、authorized、partially_paid、paid、partially_refunded、refunded、voided | | `fulfillment_status` | null (unfulfilled)、partial、fulfilled、restocked |

### 产品状态

| 状态 | 描述 | |--------|-------------| | `active` | 可供出售 | | `archived` | 不再可用，从管理列表中隐藏 | | `draft` | 尚未准备好出售 |

### 退货状态

| 状态 | 描述 | |--------|-------------| | `requested` | 客户请求退货 | | `in_progress` | 退货处理中 | | `open` | 退货已接受，等待商品 | | `closed` | 退货已完成 | | `cancelled` | 退货已取消 |

## 分页

Shopify 通过 `Link` 请求头使用基于游标的分页。

### 使用页面信息

```bash # First request curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products.json?limit=50" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -i ```

响应包含 `Link` 请求头： ``` Link: <https://store.myshopify.com/admin/api/2024-10/products.json?page_info=abc123&limit=50>; rel="next" ```

```bash # Next page curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/products.json?page_info=abc123&limit=50" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

注意：使用 `page_info` 时，除了 `limit` 和 `fields` 之外，不能使用其他查询参数。

## 速率限制

Shopify 使用漏桶算法：

- **桶大小**：40 个请求 - **漏出速率**：2 个请求/秒 - **恢复**：约 20 秒恢复满桶

响应请求头： - `X-Shopify-Shop-Api-Call-Limit`：当前使用情况（例如 `32/40`） - `Retry-After`：需等待的秒数（在 429 响应上）

### 最佳实践

1. 检查 `X-Shopify-Shop-Api-Call-Limit` 请求头 2. 如果接近限制，在请求之间添加延迟 3. 收到 429 响应时，等待 `Retry-After` 秒 4. 对大数据集使用批量操作

## Webhooks

#### 列出 Webhooks

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/webhooks.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" ```

### 创建 Webhook

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/webhooks.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{"webhook":{"topic":"orders/create","address":"https://example.com/webhooks/orders","format":"json"}}' ```

常用主题：`orders/create`、`orders/updated`、`orders/fulfilled`、`orders/cancelled`、`products/create`、`products/update`、`products/delete`、`customers/create`、`customers/update`、`inventory_levels/update`、`refunds/create`

### 删除 Webhook

```bash curl "https://$SHOPIFY_STORE_DOMAIN/admin/api/2024-10/webhooks/{WEBHOOK_ID}.json" \ -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \ -X DELETE ```

## 更新日志

### v1.0.0

- 初始版本，包含完整的 Admin REST API 覆盖 - 订单、产品、变体、客户 - 库存管理（级别、商品、地点） - 发货和发货订单 - 退款、退货、交易 - 产品系列（自定义、智能）和产品收集 - 弃单 - Webhooks 管理 - 状态参考表 - 分页和速率限制文档