Significant OpenAPI Updates

Dear Developers,

Please find below the OpenAPI updates released this time. These changes aim to enhance functionality, improve flexibility, and provide better integration support.

1. GMV Max Ads – Custom ROAS

Background

• To provide sellers with more flexibility in configuring ROAS targets for the shop GMV Max campaigns and to prevent issues caused by duplicate requests, both the create and edit endpoints have been enhanced.

Change Details

Endpoint：v2.ads.create_gms_product_campaign

New Field in Request Parameter: reference_id (optional)

• Generated by developers, used to prevent duplicate requests
• Submitting the same reference_id more than once will fail; a new reference_id must be generated to retry.
• Example: 086a16bf-49e9-4103-b7fe-c0125beb9278

New Field in Request Parameter: roas_target (optional)

• No input → Default to GMV Max Auto Bidding (Shop)
• Input 0 → GMV Max Auto Bidding (Shop)
• Input value >0 → GMV Max Custom ROAS (Shop)
• Decimal handling: truncated to one decimal place: 10.123456 → 10.1; 10.199999 → 10.1

Endpoint：v2.ads.edit_gms_product_campaign

Field Updates in Request Parameter: edit_action (required), possible values:

• change_budget
• change_duration
• pause
• resume
• (new) change_roas_target

When edit_action = change_roas_target, you must provide: roas_target (float).

Value rules follow the same logic as in the create endpoint

New Field in Request Parameter:reference_id (optional)

Impact to developer

When creating ads:

• Choose bidding mode by setting roas_target (no input/0 = Auto Bidding, >0 = Custom ROAS)

When editing ads:

• To update ROAS, set edit_action = change_roas_target and include roas_target

Effective Date: September 16, 2025

2.Remove Request Field certification_type

Background

• To improve consistency and simplify the Open API design, we have optimized the certification-related fields. This update does not affect the existing certification logic, but focuses on field maintenance.

Change Details

Endpoints:v2.product.update_item and v2.product.add_item

Request Field Removal

• The request field certification_type has been removed from v2.product.update_item and v2.product.add_item.
• If this field is still passed in requests, it will be ignored by the system without affecting processing.

Impact to developer

• No action is required for developers; existing logic will continue to function normally.
• However, we recommend updating your requests to stop passing deprecated fields, keeping the structure clean and aligned with the latest API specifications.

Effective Date: September 19, 2025

3. (TW & BR) Seller-Arranged Return Method Supports Uploading Shipping Information

Shopee currently supports the “Seller Arrange” return method in the TW (Taiwan) and BR (Brazil) markets.

To further improve return process efficiency and enhance user experience, we are adding a new capability on top of this feature: sellers will now be able to upload return shipping information (shipping carrier, tracking number, and shipping proof). Relevant API specifications have been updated accordingly.

1. Scope of Application

• Applicable Markets: TW (Taiwan), BR (Brazil)
• Feature Description: When processing returns using the “Seller Arrange” return method, sellers are required to upload the relevant shipping information (shipping carrier, tracking number, shipping proof, etc.) to Shopee after arranging the logistics. This ensures the platform and buyers are updated in time, thereby improving the return handling experience.

2. New Response Fields

3. New Related APIs

To support the “upload shipping information” scenario, the following APIs are provided:

• v2.media.upload_image: Public API for uploading images. For this scenario, please use business=2, scene=1 to upload shipping proof.

• v2.returns.get_shipping_carrier: Retrieves the list of available non-integrated return logistics carriers and their requirements for a given return_sn.

• v2.returns.upload_shipping_proof: Uploads the return shipping information.

4. API Call Flow

5. Important Notice

Starting from 2025-10-22, sellers in the TW (Taiwan) market will receive returns with is_shipping_proof_mandatory = true. Please ensure your system is updated before this date to avoid disruptions in return processing.

Effective Date: September 16, 2025

尊敬的开发者，

请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。

1. Shop GMV Max 广告支持自定义 ROAS

背景

• 为满足卖家在Shop GMV Max 广告中灵活配置 ROAS 目标的需求，并避免重复提交请求造成的资源浪费，现对广告 创建接口 与 编辑接口 同步进行了扩展。

变更细节

接口：v2.ads.create_gms_product_campaign

入参中新增字段：reference_id (可选)

• 开发者自行生成，用于防止重复请求
• 相同 reference_id 重复提交会失败，需重新生成
• 示例：086a16bf-49e9-4103-b7fe-c0125beb9278

入参中新增字段：roas_target (可选)

• 不传值 → 默认 GMV Max Auto Bidding (Shop)
• 传入 0 → GMV Max Auto Bidding (Shop)
• 传入 >0 → GMV Max Custom ROAS (Shop)
• 小数处理：保留一位小数，向下截断：10.123456 → 10.1；10.199999 → 10.1更新内容

接口：v2.ads.edit_gms_product_campaign

入参中字段更新：edit_action (必填)，可选值：

• change_budget
• change_duration
• pause
• resume
• （新增取值）change_roas_target：

当 edit_action = change_roas_target 时，需同时传入：roas_target (float)：取值规则同创建接口

入参中新增字段：reference_id(可选)

开发者操作

创建广告时：

• 根据需求选择自动出价或自定义 ROAS 出价，并传入 roas_target

编辑广告时：

• 若需修改 ROAS，使用 edit_action = change_roas_target 并传入 roas_target

生效日期: 2025年09月16日

2.下线请求字段 certification_type

背景

• 我们对认证相关字段进行了优化和清理。本次调整不影响现有认证逻辑，仅涉及字段维护。

接口

• v2.product.update_item
• v2.product.add_item

请求入参字段下线：

• 移除了 v2.product.update_item 和v2.product.add_item 请求入参中的certification_type 字段
• 若调用方仍传递该字段，系统会忽略该参数，不会影响请求的正常处理

影响

• 开发者无需对现有逻辑进行调整，只需知悉该字段将不再生效

• 建议开发者更新调用参数，避免传递已废弃字段，以保持请求结构简洁。

生效日期：2025年09月19日

3. (TW&BR) 卖家自行安排退货方式支持上传物流信息

Shopee 在 TW (台湾) 和 BR (巴西) 市场已支持“卖家自行安排”退货方式。为进一步提升退货流程效率和用户体验，我们在该功能基础上，新增卖家上传物流信息 (物流商、运单号、寄件凭证等) 的能力，并同步更新相关 API。

1. 适用范围

• 功能适用市场：TW (台湾)、BR (巴西)
• 功能说明：卖家在处理“卖家自行安排”退货方式的退货时，需在安排好退货物流后，按照平台要求将相关物流信息 (物流商、运单号、寄件凭证等) 上传至 Shopee 平台，以便平台与买家及时同步，提升退货处理体验。

2. 新增响应字段

3. 新增相关接口

为支持“上传物流信息”场景，新增以下接口：

• v2.media.upload_image：用于上传图片的通用 API；在该场景下，请使用 business=2、scene=1 上传运单凭证

• v2.returns.get_shipping_carrier：用于查询指定 return_sn 可使用的非集成退货物流商及其规则详情

• v2.returns.upload_shipping_proof：用于上传退货物流信息

4. 接口调用流程

5. 重要提示

TW (台湾) 市场的卖家将在 2025-10-22 起，收到 is_shipping_proof_mandatory = true 的退货单。请您务必在此时间前完成系统更新，以免影响退货流程处理

生效日期: 2025年09月16日