API 变更日志

追踪 Shoplazza OpenAPI 版本之间的破坏性变更、新增端点与已移除端点。版本采用 vYYYYMM 命名约定。

v202607​

版本信息​

摘要​

• 本版本为常规发布，将 API 前缀从 2026-01 递增至 2026-07。
• 使用此前缀的现有集成在新前缀下功能行为保持不变。
• 需将 API 基础路径更新为 /openapi/2026-07/ 以访问此版本；无需其他迁移步骤。

v202601​

版本信息​

摘要​

• 价格规则和折扣码端点已完全被新的统一 折扣 API 替代。
• 新的折扣端点支持自动和非自动折扣、代码查询、组合配置、批量操作和取消。
• 引入了异步智能集合创建，以提升大规模规则下的性能。
• 移除了若干旧端点（限时抢购、返利、弹窗、销售弹窗配置），无替代方案。
• 优惠券 API 变更：列表端点 GET /coupons 已移除；新增 POST /coupons 端点。

破坏性变更​

折扣与价格规则​

现有的 /price_rules 和 /discount_codes 端点被新的 /discounts 端点替代。请使用以下映射迁移代码。

优惠券​

• GET /coupons (列出优惠券) 已移除。无直接替代。
• POST /coupons 已新增（见新增部分）。

新增​

以下为新增端点：

• 优惠券
  • POST /coupons — 创建优惠券
  • GET /coupons/{id} — 获取优惠券
  • PUT /coupons/{id} — 更新优惠券
• 折扣
  • GET /discounts — 列出折扣
  • POST /discounts/automatic — 创建自动折扣
  • PUT /discounts/automatic/{id} — 更新自动折扣
  • POST /discounts/batch-delete — 批量删除折扣
  • GET /discounts/by-code/{discount_code} — 按代码获取折扣
  • POST /discounts/cancel — 取消折扣
  • PUT /discounts/combine — 配置可组合的折扣类型
  • POST /discounts/non-automatic — 创建非自动折扣
  • PUT /discounts/non-automatic/{id} — 更新非自动折扣
  • POST /discounts/restart — 重启折扣
  • GET /discounts/{id} — 获取折扣
  • DELETE /discounts/{id} — 删除折扣
• 集合
  • POST /collections/async — 异步创建智能集合
  • GET /collections/async-task/{id} — 获取集合异步任务
  • PATCH /collections/{id}/smart-rule — 更新智能集合规则
  • PATCH /collections/{id}/smart-rule/async — 异步更新智能集合规则

变更（非破坏性）​

• DELETE /products — 删除产品（现有路径的新方法）。

移除且无替代​

以下端点已被移除，无直接替代：

• POST /coupons/receive — 接收优惠券
• GET /discount_flash_sales — 列出限时抢购
• GET /discount_rebates — 列出返利
• GET /popups — 列出弹窗
• GET /price_rules/count — 获取价格规则数量
• POST /price_rules/{price_rule_id}/discount_codes/batch — 批量创建折扣码
• GET /salespops/config — 获取销售弹窗配置

迁移指引​

1. 价格规则到折扣：将所有对 /price_rules 和 /discount_codes 的调用替换为破坏性变更表格中对应的 /discounts 端点。注意新 API 需要区分自动和非自动折扣。
2. 优惠券列表：如果您的应用依赖 GET /coupons 列出优惠券，请使用新的 GET /discounts 端点（包含所有折扣类型）或通过 GET /coupons/{id} 单个获取优惠券。
3. 批量创建折扣码：批量端点已移除。请使用 POST /discounts/non-automatic 逐个创建折扣。
4. 计数端点：使用 GET /discounts 的分页（page/limit）替代已移除的 /price_rules/count。

Schema 与行为​

字段级别变更未在此变更日志中列出。有关详细的请求/响应 Schema 和行为变更，请参阅 API 参考。

v202506​

版本信息​

摘要​

• 整合数据分析 – 旧数据端点已被统一 /data-analysis API 替代，支持按 SKU、SPU、着陆页和 UTM 的细粒度洞察。
• 现代化库存管理 – 库存项目和库存水平的完整 CRUD，以及支持优先级和停用的位置管理。
• 简化支付与结算 – 所有 shoplazza-payment 端点现已添加版本前缀，提供对余额、争议、付款、退款和结算的一致访问。
• 精简资源路径 – 关键资源（orders、customers、procurements、script_tags、metafields）采用更简洁且参数一致的路径。
• 新能力 – 应用代理、文章与博客、礼品卡批量创建、主题文件版本管理以及高级运输 Schema 管理现已可用。

破坏性变更​

运输服务​

• POST /carrier_services/（带尾斜杠）端点已移除。请使用不带尾斜杠的新 POST /carrier_services。

数据分析​

• 旧端点 GET /data/analysis、GET /data/count、GET /data/query、GET /data/task 和 GET /data/tasks 已移除，无直接替代。请使用新的数据分析 API。

文件​

• GET /{ver}/file/{file_uri} 方法已移除。

库存与位置​

• GET /{ver}/statistics/inventory/cost_price 和 GET /{ver}/statistics/inventory/loss_quantity 端点已移除。请使用新的库存项目和库存水平端点。

订单与客户​

• 所有订单和客户子端点现使用 {order_id} 和 {customer_id} 代替 {id}。

支付应用回调​

• POST /payments_apps/complete_callbacks 和 POST /payments_apps/notify_callbacks 端点已移除。请使用新的 POST /payments_apps/configure 进行配置；回调处理可能由 Webhook 替代。

价格规则​

• DELETE /{ver}/price_rules/{price_rule_id}/discount_codes 方法已移除。请使用 DELETE /{ver}/price_rules/{price_rule_id}/discount_codes/{discount_code_id} 删除单个折扣码。

采购与库存管理​

• 所有采购端点已从 /center/procurements 和直接 /procurements 迁移到统一的 /procurements/{procurement_id} 模式。

定期应用收费​

• 路径现使用 {charge_id} 代替 {recurring_charge_id}。

脚本标签​

• 旧的 script_tags_new 端点已移除。请使用新的 /script_tags 端点（不带 _new）。

Metafields​

• Metafield 路径已重组为 /metafields/{owner_resource}/{owner_id}。商店级别的 Metafield 现位于 /metafields-shop。

区域​

• 区域端点现使用 {country} 代替 {country_code}，并新增 POST/DELETE 支持。

限时抢购折扣​

• 端点从 discount_flashsales 重命名为 discount_flash_sales。

主题​

• 若干主题端点已移除。请使用新的主题版本管理和文件管理端点。

追踪​

• GET /{ver}/tracking-codes 已移除。请使用新的 /tracking/carriers 端点。

其他移除​

• GET /{ver}/salespops/datagraph 已移除，无替代。
• GET /{ver}/orders/after_sales_list 已移除。请使用 GET /{ver}/orders/post_sales。

新增​

• 应用代理 – GET/POST /{ver}/app-proxies、GET /{ver}/app-proxies/count、GET/DELETE /{ver}/app-proxies/{id}
• 应用收费 – GET /{ver}/application_charges/{charge_id}/transactions
• 区域 – POST/DELETE /{ver}/areas/country/{country}/province、GET /{ver}/areas/{code}/children
• 文章与博客 – /articles 和 /blogs 的完整 CRUD（列表、创建、获取、更新、删除、计数、作者）
• 分类 – GET /{ver}/categories
• 收藏 – POST /{ver}/collects/batch
• 数据分析 – POST /{ver}/data-analysis、/data-analysis/land-page、/data-analysis/sku、/data-analysis/spu、/data-analysis/utm
• 限时抢购折扣 – GET /{ver}/discount_flash_sales
• 文件 – GET /{ver}/file/detail/{file_uri}
• 礼品卡 – POST /{ver}/gift_cards/batch
• 库存 – /inventory_items 和 /inventory_levels 的完整 CRUD，以及 /inventory_items/variant、/inventory_items/{inventory_item_id}、/inventory_levels/set
• 位置 – 管理端点：列表、计数、停用、默认、优先级、按 ID 获取、按位置列出库存水平
• Metafields – 商店级别（/metafields-shop）和资源级别（/metafields/{owner_resource}/{owner_id}），支持 CRUD 和计数
• OAuth – GET /{ver}/oauth/access_scopes
• 订单 – GET /{ver}/orders/post_sales
• 页面 – POST /{ver}/pages/details、DELETE /{ver}/pages/store-pages/batch、GET /{ver}/pages/store-pages/info
• 支付 – GET /{ver}/payment/channels
• 支付应用 – POST /{ver}/payments_apps/configure
• 价格规则 – POST /{ver}/price_rules/{price_rule_id}/discount_codes/batch
• 采购 – 新增 PUT 方法，合并 /items（现包含批量更新）
• 定期应用收费 – GET /{ver}/recurring_application_charges/{charge_id}/transactions
• 脚本标签 – 以 /script_tags 替代 script_tags_new
• 运输 – POST /{ver}/shipping-lines/available-lines、GET/POST /{ver}/shipping-schemas/general、POST /{ver}/shipping-schemas/shipping-zone、PUT/DELETE /{ver}/shipping-schemas/shipping-zone/{id}
• Shoplazza 支付 – 新增 GET /{ver}/shoplazza-payment/balance 和 GET /{ver}/shoplazza-payment/balance/details
• 主题 – GET /{ver}/themes/task/{task_id}、PUT /{ver}/themes/{theme_id}/doc-rename、多个版本相关端点
• 追踪 – GET /{ver}/tracking/carriers、GET /{ver}/tracking/carriers/detect
• 交易 – GET /{ver}/transactions/{transaction_id}

变更​

以下端点新增了方法，不会破坏现有调用：

• POST /{ver}/carrier_services – 创建运输服务的新端点。
• GET /{ver}/orders/{order_id}/risks – 获取订单风险信息的新方法。
• DELETE /{ver}/pages/{id} – 删除页面的新方法。
• DELETE /{ver}/price_rules/{price_rule_id}/discount_codes/{discount_code_id} – 删除单个折扣码的新方法。

移除且无替代​

以下端点已被移除，且无直接替代：

• GET /{ver}/data/count
• GET /{ver}/orders/after_sales_list
• GET /{ver}/salespops/datagraph
• GET /{ver}/statistics/inventory/cost_price
• GET /{ver}/statistics/inventory/loss_quantity
• POST /{ver}/themes/upload
• POST /{ver}/themes/{theme_id}/doc-asset
• GET /{ver}/themes/{theme_id}/download
• POST /{ver}/payments_apps/complete_callbacks
• POST /{ver}/payments_apps/notify_callbacks

迁移指引​

1. 路径与参数更新 – 将所有请求更新为使用新的参数名称（{order_id}、{customer_id}、{procurement_id}、{charge_id}、{script_tag_id} 等）以及破坏性变更表格中所示的新路径。从采购和库存端点中移除旧的 /center/ 前缀。

2. 数据分析 – 将已移除的 GET /data/* 端点的调用替换为新的 POST /data-analysis 端点。根据分析类型（SPU、SKU、着陆页、UTM）使用适当的子端点。旧的 GET /data/count 无替代。

3. 库存统计 – statistics/inventory 端点已不存在。使用 /inventory_items、/inventory_levels 和 /locations 查询库存数据。

4. 支付应用回调 – 如果您使用了 complete_callbacks 或 notify_callbacks，请迁移到 POST /payments_apps/configure 端点，并考虑使用 Webhook 处理回调。

5. 主题上传与下载 – 主题上传/下载已移除。使用 /themes/{theme_id}/upgrade 升级主题，以及新的文件管理端点进行资产操作。

6. 折扣码 – 不再支持通过 DELETE /discount_codes 批量删除折扣码。请使用 DELETE /discount_codes/{discount_code_id} 删除单个代码，或使用新的 POST /discount_codes/batch。

7. Metafields – 从动态的 /{resource}/{resource_id}/metafields 模式迁移到专门的 /metafields/{owner_resource}/{owner_id} 路径。商店 metafields 现拥有自己的端点位于 /metafields-shop。

Schema 与行为​

字段级别变更未在此变更日志中列出。有关请求/响应 Schema 的详细信息，请参阅 API 参考。

v202201​

版本信息​

摘要​

• 此版本建立了 2022-01 API 的初始变更日志基线。
• API 前缀为 /openapi/2022-01/，共涵盖 150 个端点。
• 此版本中的所有现有端点保持不变；无先前版本可供比较。
• 此基线作为未来所有破坏性变更、新增和移除的参考点。
• 此版本中不存在影响客户端的变更，仅用于锚定变更日志历史。