API 变更日志

追踪 Shoplazza OpenAPI 版本之间的破坏性变更、新增端点及移除端点。版本遵循 vYYYYMM 命名规范。

v202601​

版本信息​

摘要​

• 折扣管理整合至新的 /discounts API，替代所有 price_rules 和 discount_codes 端点。
• 优惠券端点重构：移除 POST /coupons/receive 端点，/coupons 的 get 方法替换为 POST 方法。新增专属 coupons/{id} 资源用于读取和更新。
• popups 和 salespops/config 端点被移除且无替代。
• /products 新增 DELETE 方法，支持删除商品。
• /collections/{id}/smart-rule 新增 PATCH 方法，用于更新智能集合规则。

破坏性变更​

折扣（价格规则与折扣码）​

/price_rules 和 /discount_codes 下的所有端点均被新的 /discounts API 替代。下表映射了旧端点与新端点。

此外，GET /discount_flash_sales 和 GET /discount_rebates 被移除且无替代。

优惠券​

• GET /coupons 替换为 POST /coupons。依赖 GET 方法的现有集成必须改为使用 POST（带上适当的请求体）来创建优惠券。
• POST /coupons/receive 被移除且无替代。

新增​

集合​

• PATCH /collections/{id}/smart-rule — 更新智能集合规则

优惠券​

• 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} — 删除折扣

变更（非破坏性）​

• DELETE /products — 删除商品（新增方法；现有的 GET 和 POST 保持不变）

移除且无替代​

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

• POST /coupons/receive
• GET /discount_flash_sales
• GET /discount_rebates
• GET /popups
• GET /salespops/config

迁移指引​

1. 替换价格规则与折扣码调用：将所有使用 /price_rules 或 /discount_codes 路径的集成更新为对应的 /discounts 端点，如上表所示。
2. 更新优惠券列表调用：将 GET /coupons 替换为 POST /coupons 以创建优惠券；使用新的 GET /coupons/{id} 检索单个优惠券。
3. 移除已废弃的调用：删除所有对 POST /coupons/receive、GET /discount_flash_sales、GET /discount_rebates、GET /popups 和 GET /salespops/config 的引用。
4. 利用新功能：使用新的 DELETE /products 端点删除商品，以及 PATCH /collections/{id}/smart-rule 更新智能集合规则。

Schema 与行为​

本变更日志未列出请求或响应 schema 中的字段级变更。请参考 API 参考 获取完整的 schema 详情。

v202506​

版本信息​

摘要​

• 资源路径重构 – 许多核心端点（订单、客户、采购、循环应用费用）重命名了路径参数（例如 {id} → {order_id}）并更新了前缀，需要更新代码。
• 新增计费与支付能力 – 新增了应用费用交易和 Shoplazza 支付余额的端点，扩展了财务数据访问。
• 库存管理全面改革 – 引入了专门的 inventory_items、inventory_levels 和 locations 端点，替代了旧的库存统计。
• 弃用旧模块 – 与中心相关的（采购/库存/调拨）端点以及多个数据分析端点被移除且无直接替代。
• 简化的 Webhook 与主题管理 – Script tags 重命名，主题新增版本控制和升级支持，支付应用配置简化。

破坏性变更​

客户​

订单​

采购​

循环应用费用​

Script Tags​

Metafields​

数据分析​

限时抢购​

地区/省份​

Shoplazza 支付​

/openapi/2024-07/shoplazza-payment/ 下的所有 GET 端点均被 /openapi/2025-06/shoplazza-payment/ 下的相同端点替代。功能无变化，但前缀已更新。

承运商服务​

价格规则 – 折扣码​

页面​

文件​

新增​

应用费用​

• GET /openapi/2025-06/application_charges/{charge_id}/transactions — 列出一次性应用费用交易

地区​

• POST /openapi/2025-06/areas/country/{country}/province — 创建省份
• DELETE /openapi/2025-06/areas/country/{country}/province — 删除省份
• GET /openapi/2025-06/areas/{code}/children — 列出子地区

文章与博客​

• GET /openapi/2025-06/articles — 列出文章
• POST /openapi/2025-06/articles — 创建文章
• GET /openapi/2025-06/articles/authors — 列出作者
• GET /openapi/2025-06/articles/count — 获取文章数量
• GET /openapi/2025-06/articles/{id} — 获取文章
• PUT /openapi/2025-06/articles/{id} — 更新文章
• DELETE /openapi/2025-06/articles/{id} — 删除文章
• GET /openapi/2025-06/blogs — 列出博客
• POST /openapi/2025-06/blogs — 创建博客
• GET /openapi/2025-06/blogs/count — 获取博客数量
• GET /openapi/2025-06/blogs/{id} — 获取博客
• PUT /openapi/2025-06/blogs/{id} — 更新博客
• DELETE /openapi/2025-06/blogs/{id} — 删除博客

分类​

• GET /openapi/2025-06/categories — 列出分类

收藏​

• POST /openapi/2025-06/collects/batch — 批量创建收藏

数据分析​

• POST /openapi/2025-06/data-analysis/land-page — 获取数据分析落地页
• POST /openapi/2025-06/data-analysis/sku — 按 SKU 获取数据分析
• POST /openapi/2025-06/data-analysis/utm — 获取数据分析 UTM

文件​

• GET /openapi/2025-06/file/detail/{file_uri} — 获取文件

礼品卡​

• POST /openapi/2025-06/gift_cards/batch — 批量创建礼品卡

库存​

• GET /openapi/2025-06/inventory_items — 列出库存项
• GET /openapi/2025-06/inventory_items/variant — 列出变体库存项
• GET /openapi/2025-06/inventory_items/{inventory_item_id} — 获取库存项
• PUT /openapi/2025-06/inventory_items/{inventory_item_id} — 更新库存项
• GET /openapi/2025-06/inventory_levels — 列出库存水平
• PUT /openapi/2025-06/inventory_levels — 更新库存水平
• POST /openapi/2025-06/inventory_levels — 创建库存水平
• DELETE /openapi/2025-06/inventory_levels — 删除库存水平
• POST /openapi/2025-06/inventory_levels/set — 设置库存水平
• GET /openapi/2025-06/locations — 列出位置
• GET /openapi/2025-06/locations/count — 统计位置数量
• POST /openapi/2025-06/locations/deactivate — 停用位置
• GET /openapi/2025-06/locations/default — 获取默认位置
• PUT /openapi/2025-06/locations/default — 更改默认位置
• POST /openapi/2025-06/locations/priority — 编辑位置优先级
• GET /openapi/2025-06/locations/{location_id} — 获取位置
• GET /openapi/2025-06/locations/{location_id}/inventory_levels — 列出库存水平

Metafields（店铺）​

• GET /openapi/2025-06/metafields-shop — 列出店铺 metafields
• POST /openapi/2025-06/metafields-shop — 创建店铺 metafield
• GET /openapi/2025-06/metafields-shop/count — 获取店铺 metafield 数量
• GET /openapi/2025-06/metafields-shop/{id} — 获取店铺 metafield
• DELETE /openapi/2025-06/metafields-shop/{id} — 删除店铺 metafield
• PATCH /openapi/2025-06/metafields-shop/{id} — 更新店铺 metafield

OAuth​

• GET /openapi/2025-06/oauth/access_scopes — 列出访问范围

订单​

• GET /openapi/2025-06/orders/post_sales — 列出售后订单

页面​

• POST /openapi/2025-06/pages/details — 批量获取页面
• DELETE /openapi/2025-06/pages/store-pages/batch — 批量删除页面
• GET /openapi/2025-06/pages/store-pages/info — 搜索页面

支付​

• GET /openapi/2025-06/payment/channels — 获取可用支付渠道列表
• POST /openapi/2025-06/payments_apps/configure — 配置支付应用

价格规则​

• POST /openapi/2025-06/price_rules/{price_rule_id}/discount_codes/batch — 批量创建折扣码

采购（新方法）​

• PUT /openapi/2025-06/procurements/{procurement_id}/items — 批量更新采购项

循环应用费用（新增）​

• GET /openapi/2025-06/recurring_application_charges/{charge_id}/transactions — 列出循环应用费用交易

配送​

• POST /openapi/2025-06/shipping-lines/available-lines — 获取可用配送线路
• GET /openapi/2025-06/shipping-schemas/general — 获取通用配送方案
• POST /openapi/2025-06/shipping-schemas/general — 保存通用配送方案
• PUT /openapi/2025-06/shipping-schemas/shipping-zone — 更新配送区域
• POST /openapi/2025-06/shipping-schemas/shipping-zone — 创建配送区域
• DELETE /openapi/2025-06/shipping-schemas/shipping-zone — 删除配送区域

Shoplazza 支付（新增）​

• GET /openapi/2025-06/shoplazza-payment/balance — 获取余额
• GET /openapi/2025-06/shoplazza-payment/balance/details — 列出余额明细

主题​

• GET /openapi/2025-06/themes/task/{task_id} — 获取主题任务
• PUT /openapi/2025-06/themes/{theme_id}/doc-rename — 重命名主题文件
• GET /openapi/2025-06/themes/{theme_id}/doc/version-records — 列出主题文件版本（所有文件）
• GET /openapi/2025-06/themes/{theme_id}/doc/versions — 列出主题文件版本（单个文件）
• GET /openapi/2025-06/themes/{theme_id}/doc/versions/{version_id} — 按 ID 获取主题文件版本
• POST /openapi/2025-06/themes/{theme_id}/upgrade — 升级特定主题

追踪​

• GET /openapi/2025-06/tracking/carriers — 列出承运商
• GET /openapi/2025-06/tracking/carriers/detect — 通过运单号检测承运商

交易​

• GET /openapi/2025-06/transactions/{transaction_id} — 获取应用费用交易

移除且无替代​

以下端点已移除，本版本无直接功能替代：

• /openapi/2022-01/center/procurements (GET)
• /openapi/2022-01/center/procurements/{procurement_id} (GET)
• /openapi/2022-01/center/procurements/{procurement_id}/items (GET)
• /openapi/2022-01/center/stock_adjust_orders (GET)
• /openapi/2022-01/center/stock_adjust_orders/{stock_adjust_order_id}/items (GET)
• /openapi/2022-01/center/stock_adjust_orders/{stock_adjust_orders_id} (GET)
• /openapi/2022-01/center/transfer_orders (GET)
• /openapi/2022-01/center/transfer_orders/{transfer_order_id} (GET)
• /openapi/2022-01/center/transfer_orders/{transfer_order_id}/items (GET)
• /openapi/2022-01/orders/{id}/partial_refund (POST)
• /openapi/2022-01/salespops/datagraph (GET)
• /openapi/2022-01/statistics/inventory/cost_price (GET)
• /openapi/2022-01/statistics/inventory/loss_quantity (GET)
• /openapi/2022-01/themes/upload (POST)
• /openapi/2022-01/themes/{theme_id}/doc-asset (POST)
• /openapi/2022-01/themes/{theme_id}/download (GET)
• /openapi/2022-01/payments_apps/complete_callbacks (POST)
• /openapi/2022-01/payments_apps/notify_callbacks (POST)

迁移指引​

1. 更新所有路径参数 – 将 {id} 替换为 {order_id}、{customer_id}、{procurement_id}、{charge_id} 和 {script_tag_id}，如破坏性变更表中所示。更新 API 客户端配置，使用新的基础 URL /openapi/2025-06/。
2. 切换到新的数据分析端点 – 将之前的 GET /data/analysis、/data/count、/data/query、/data/task 和 /data/tasks 替换为新的 POST /data-analysis 及其子资源（/land-page、/sku、/spu、/utm）。
3. 采用新的 Metafield 路径模式 – 使用 /metafields/{owner_resource}/{owner_id} 替代 /{resource}/{resource_id}/metafields。所有者资源现在作为路径参数显式传递。
4. 替换追踪码与承运商服务 – 从 GET /tracking-codes 迁移到 GET /tracking/carriers 和 POST /tracking/carriers/detect。对于承运商服务，确保移除端点路径中的尾部斜线。
5. 处理已移除的端点 – 如果你依赖中心库存操作、部分退款、销售弹窗分析或主题上传/下载，请评估新的库存管理端点或考虑替代工作流。这些没有提供直接替代方案。

Schema 与行为​

本变更日志未列出字段级变更。有关详细的请求和响应 schema，请参考 /api/openapi。请注意，POST /orders/{order_id}/transactions 端点已被移除；请使用新的 /transactions/{transaction_id} 端点检索交易详情。此外，折扣码列表端点上的 DELETE 方法已被移除；请改用按代码删除端点。

v202201​

版本信息​

摘要​

• 此版本是 Shoplazza OpenAPI 的第一个版本，作为未来变更日志的基线。
• 此版本没有破坏性变更、新增或移除。
• 此版本中记录的所有端点均被视为当前稳定版本。
• 开发者在升级到更新版本时应参考此基线。