如何通过Shopify API获取店铺全量订单数据？

权限配置说明 #

• 自用自定义私有应用（不上架Shopify应用商店，仅服务单个自有站点）：无需申请已受限的read_all_orders权限，仅需给应用配置基础的read_orders权限即可访问店铺全生命周期的订单数据。read_all_orders权限限制仅针对上架分发的公共应用，私有应用不受该规则约束，不要被过时的第三方文档误导。
• 需上架的公共应用：确实无法获取read_all_orders权限，默认仅能拉取最近60天的订单，这类场景要做全量数据必须提前配置订单相关webhook，新订单产生/更新时实时落库到自有存储，长期积累形成全量数据集。

全量拉取核心逻辑（解决单次返回250条上限问题） #

Shopify自2019-07版本API开始强制使用游标分页机制，单次请求limit参数最大值为250，不存在任何配置项可以突破该单次返回上限，全量拉取的唯一官方支持方案是遍历分页游标。

通用请求流程 #

1. 构造首次请求地址：https://{店铺专属myshopify域名}/admin/api/{指定API版本，建议选当前稳定版如2024-01}/orders.json?limit=250&status=any，必须携带status=any参数，否则接口默认仅返回状态为open的订单，会漏掉已取消、已归档的订单数据。
2. 请求头携带X-Shopify-Access-Token: {私有应用访问令牌}做鉴权。
3. 每次请求后解析响应头中的Link字段，该字段会标注下一页的接口地址，格式参考：

   Link: <https://demo.myshopify.com/admin/api/2024-01/orders.json?limit=250&page_info=eyJsYXN0X2lkIjoyMDQ5OTY4Mzg5MTI5fQ==>; rel="next"
   

4. 只要Link头中存在rel="next"标记的地址，就继续请求该地址获取下一页数据，直到响应头中无next标记，即完成全量订单拉取。

注意：page_info参数是Shopify动态生成的加密游标，不要自行拼接构造，必须从上一次请求的响应Link头中提取，否则会返回参数错误。

适配常用技术栈的实现参考 #

PHP 可运行代码片段

<?php
$shopDomain = '替换为你的店铺myshopify域名';
$accessToken = '替换为你的私有应用访问令牌';
$apiVersion = '2024-01';
$allOrders = [];
$nextUrl = "https://{$shopDomain}/admin/api/{$apiVersion}/orders.json?limit=250&status=any";

while ($nextUrl) {
    $ch = curl_init($nextUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "X-Shopify-Access-Token: {$accessToken}",
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_HEADER, true);
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    $respHeaders = substr($response, 0, $headerSize);
    $respBody = json_decode(substr($response, $headerSize), true);
    curl_close($ch);

    if ($httpCode !== 200) {
        // 触发Shopify限流时等待1秒重试
        if ($httpCode === 429) {
            sleep(1);
            continue;
        }
        break;
    }

    $allOrders = array_merge($allOrders, $respBody['orders']);
    $nextUrl = null;
    // 从响应头提取下一页地址
    if (preg_match('/<([^>]+)>;\s*rel="next"/', $respHeaders, $matches)) {
        $nextUrl = $matches[1];
    }
}
// 最终$allOrders即为全量订单数组，可直接写入数据库或同步到FileMaker
?>

FileMaker 对接方案

• 低复杂度方案：将上述PHP脚本部署为本地接口，FileMaker通过Insert from URL脚本步骤直接调用该接口获取整理好的全量订单JSON，再通过内置JSON函数解析写入对应表即可，无需在FileMaker内处理分页、响应头解析逻辑。
• 纯FileMaker实现：发请求时开启返回响应头的配置，每次请求后通过文本处理函数提取Link头中的next地址，循环发起请求直到无下一页标记即可，遇到429限流错误时插入等待脚本步骤即可。

效率优化建议 #

首次完成全量拉取后，后续同步无需每次遍历所有分页，只需在请求参数中追加updated_at_min={上次同步的时间戳}，即可仅拉取该时间点之后新增或修改的订单，大幅降低请求量，减少限流触发概率。

常见踩坑 #

• 不要使用旧版文档提到的since_id参数做分页，游标分页的稳定性和性能远高于旧分页方案，是官方当前唯一推荐的分页方式。
• 日文站点的API返回字段结构和英文站点完全一致，仅订单内的商品名、收货地址等业务内容为日文，无需做额外的接口适配，直接按官方字段定义解析即可。
• 自用私有应用无需走OAuth授权流程，直接在应用管理后台生成永久访问令牌即可使用，减少不必要的开发量。

内容的提问来源于stack exchange，提问作者jp_hi