快工助手跨境电商知识与商机助手

v2.product.update_tier_variation

Shopee 官方资料 · Shopee Open Platform 接口参考 · 适合开发者

stable本次发布有变化全部展示

来自 Shopee 官方资料快照 ·

打开官方原文 ↗
  1. 当前资料结构化阅读页
  2. 固定快照已留存,可追溯
  3. 官方原文可核对
查看技术与溯源信息
平台 / profile
Shopee / profile.shopee.api_reference
语言
en-US
发布版本
cn-20260909-2
标签
zhuge/sourceplatform/shopeeaudience/developercategory/api_doctopic/apitopic/developer

资料正文

§1 v2.product.update_tier_variation

This api can only be used without changing the tier structure, you can add options, delete options, and update the option image by this api. More detail please check: https://open.shopee.com/developer-guide/219

#

§2 Overview

Overview

FieldValue
ModuleProduct
API typeShop
HTTP methodPOST
Path/api/v2/product/update_tier_variation
Production URLhttps://partner.shopeemobile.com/api/v2/product/update_tier_variation
Sandbox URLhttps://partner.test-stable.shopeemobile.com/api/v2/product/update_tier_variation
Rate limit[0, 0, 0]
PermissionERP System; Seller In House System; Product Management
#

§3 Request parameters

Request parameters

NameTypeRequiredSampleDescription
item_idint64Yes1000ID of item.
model_listobject[]NoItem's model list
model_list.model_idint64Yes1002066586922ID of model
model_list.tier_indexint64[]Yes[1,1]Model's tier_variation
standardise_tier_variationobject[]Noitem standardise tier variation There is at least one standardise_tier_variation and tier_variation
standardise_tier_variation.variation_idint64Yesstandardise tier variation ID
standardise_tier_variation.variation_namestringNostandardise tier variation name
standardise_tier_variation.variation_group_idint64Nostandardise tier variation group id
standardise_tier_variation.variation_option_listobject[]Yesstandardise tier variation option list
standardise_tier_variation.variation_option_list.variation_option_idint64Yesstandardise tier variation option ID
standardise_tier_variation.variation_option_list.variation_option_namestringNostandardise tier variation option value
standardise_tier_variation.variation_option_list.image_idstringNoID of image
#

§4 Response parameters

Response parameters

NameTypeRequiredSampleDescription
errorstringIndicate error type if hit error. Empty if no error happened.
messagestringIndicate error details if hit error. Empty if no error happened.
warningstringWarning message.
request_idstringThe identifier for an API request for error tracking
#

§5 Common parameters

Common parameters

NameTypeRequiredSampleDescription
partner_idint1Partner ID is assigned upon registration is successful. Required for all requests.
timestamptimestamp1610000000This is to indicate the timestamp of the request. Required for all requests. Expires in 5 minutes.
access_tokenstringc09222e3fc40ffb25fc947f738b1abf1The token for API access, using to identify your permission to the api. Valid for multiple use and expires in 4 hours.
shop_idint600000Shopee's unique identifier for a shop. Required param for most APIs.
signstringe318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2Signature generated by partner_id, api path, timestamp, access_token, shop_id and partner_key via HMAC-SHA256 hashing algorithm. More details: https://open.shopee.com/documents?module=87&type=2&id=58&version=2
#

§6 Request samples

Request samples

#

§7 Payload

Payload

{"item_id":40764494243,"model_list":[{"model_id":276195602326,"tier_index":[0]},{"model_id":276195602327,"tier_index":[1]},{"model_id":276195602328,"tier_index":[2]},{"model_id":276195602329,"tier_index":[3]},{"model_id":276195602330,"tier_index":[4]},{"model_id":276195602331,"tier_index":[5]},{"model_id":276195602332,"tier_index":[6]},{"model_id":276195602333,"tier_index":[7]},{"model_id":276195602334,"tier_index":[8]},{"model_id":276195602335,"tier_index":[9]},{"model_id":276195602336,"tier_index":[10]},{"model_id":276195602337,"tier_index":[11]},{"model_id":276195602338,"tier_index":[12]},{"model_id":276195602339,"tier_index":[13]},{"model_id":276195602340,"tier_index":[14]},{"model_id":276195602341,"tier_index":[15]}],"standardise_tier_variation":[{"variation_id":0,"variation_name":"Warna","variation_option_list":[{"variation_option_id":0,"variation_option_name":"GSCM A1","image_id":"id-11134207-7ra0j-mdpqg26q6lawfe"},{"variation_option_id":0,"variation_option_name":"GSCM A2","image_id":"id-11134207-7ra0o-mdpqg26q7zvcec"},{"variation_option_id":0,"variation_option_name":"GSCM A3","image_id":"id-11134207-7ra0j-mdpqg26q9efsa1"},{"variation_option_id":0,"variation_option_name":"GSCM A4","image_id":"id-11134207-7ra0r-mdpqg26qat0874"},{"variation_option_id":0,"variation_option_name":"GSCM A5","image_id":"id-11134207-7ra0n-mdpqeryrcrovc6"},{"variation_option_id":0,"variation_option_name":"GSCM A6","image_id":"id-11134207-7ra0o-mdpqeryre69b67"},{"variation_option_id":0,"variation_option_name":"GSCM A7","image_id":"id-11134207-7ra0o-mdpqeryrfktra9"},{"variation_option_id":0,"variation_option_name":"GSCM A8","image_id":"id-11134207-7ra0p-mdpqeryrgze7c6"},{"variation_option_id":0,"variation_option_name":"GSCM A9","image_id":"id-11134207-7ra0h-mdpqeryridyne5"},{"variation_option_id":0,"variation_option_name":"GSCM A10","image_id":"id-11134207-7ra0u-mdpqeryrjsj36d"},{"variation_option_id":0,"variation_option_name":"GSCM A11","image_id":"id-11134207-7ra0l-mdpqeryrl73j59"},{"variation_option_id":0,"variation_option_name":"GSCM A12","image_id":"id-11134207-7ra0i-mdpv3c3tk70s2d"},{"variation_option_id":0,"variation_option_name":"GSCM A13","image_id":"id-11134207-7ra0l-mdpv3c3tlll891"},{"variation_option_id":0,"variation_option_name":"GSCM A14","image_id":"id-11134207-7ra0o-mdpv3c3tn05o55"},{"variation_option_id":0,"variation_option_name":"GSCM A15","image_id":"id-11134207-7ra0l-mdpv3c3toeq4eb"},{"variation_option_id":0,"variation_option_name":"GSCM A16","image_id":"id-11134207-7ra0i-mdpv3c3tptak60"}]}]}
#

§8 Java

Java

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://partner.uat.shopeemobile.com/api/v2/product/update_tier_variation?sign=sign&access_token=access_token&timestamp=timestamp&shop_id=shop_id&partner_id=partner_id")
.header("Content-Type","application/json")
.body("{
   \"item_id\": 1000,
   \"tier_variation\": [
      {
         \"name\": \"-\",
         \"option_list\": [
            {
               \"image\": {
                  \"image_id\": \"-\"
               },
               \"option\": \"-\"
            }
         ]
      }
   ]
}")
.asString();
#

§9 PHP

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://partner.uat.shopeemobile.com/api/v2/product/update_tier_variation?access_token=access_token&partner_id=partner_id&shop_id=shop_id&sign=sign&timestamp=timestamp',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
    "item_id": 1000,
    "tier_variation": [
        {
            "name": "-",
            "option_list": [
                {
                    "image": {
                        "image_id": "-"
                    },
                    "option": "-"
                }
            ]
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
#

§10 cURL

cURL

curl --location --request POST 'https://partner.uat.shopeemobile.com/api/v2/product/update_tier_variation?access_token=access_token&timestamp=timestamp&shop_id=shop_id&partner_id=partner_id&sign=sign' \
--header 'Content-Type: application/json' \
--data-raw '{
   "item_id": 1000,
   "tier_variation": [
      {
         "name": "-",
         "option_list": [
            {
               "image": {
                  "image_id": "-"
               },
               "option": "-"
            }
         ]
      }
   ]
}'
#

§11 Python

Python

import requests
import json

url = "https://partner.uat.shopeemobile.com/api/v2/product/update_tier_variation?access_token=access_token&partner_id=partner_id&shop_id=shop_id&sign=sign&timestamp=timestamp"

payload=json.dumps({
  "item_id": 1000,
  "tier_variation": [
    {
      "name": "-",
      "option_list": [
        {
          "image": {
            "image_id": "-"
          },
          "option": "-"
        }
      ]
    }
  ]
})
headers = {
  'Content-Type': 'application/json'
}
response = requests.request("POST",url,headers=headers, data=payload, allow_redirects=False)

print(response.text)
#

§12 Response sample

Response sample

#

§13 JSON

JSON

{
	"error": "-",
	"message": "-",
	"warning": "-",
	"request_id": "-"
}
#

§14 Errors

Errors

ErrorDescriptionSolution
error_tier_indexThe tier_index is not exist
error_duplicate_modelidThe model_id is duplicate, model_id:{{.model_id}}
product.error_busiThe GTIN code is mandatory, please check and upload again.
error_wrong_modelidThe model_id is wrong or not related to this item, model_id:{{.model_id}}
error_networkInner http call failed
error_dataparse data failed
error_datadata not exist
error_paramparameter invalid
error_paramThe information you queried is not found.
error_paramWrong parameters, detail: {msg}.
error_serverSomething wrong. Please try later.
error_shopshopid is invalid
error_paramrequest not from gateway
error_auth_model_is_pffItem/Model Fulfillment by Shopee can not be update.
error_item_not_belong_shopItem not belong to shop.
error_param_shop_id_not_foundShop_id is not found.
error_paramCanot change the level of tier-variation.
error_paramModel tier_index error.
error_paramImage not exist.
error_paramCount of tier_variation options should be under 50. Count of 2-level variations combinations should be under 50.
error_busi_cannot_delete_all_modelCannot delete all models by this api.
error_tier_var_level_not_sameItem tier-variation level not same
error_tier_var_is_Item without tier-variation. Please use init_tier_variation api to upgrade the structure.
error_innerOur system is taking some time to respond, please try later.
error_innerSystem error, please try again later or contact the OpenAPI support team.
error_unknown{{.error_info}}
error_item_not_foundProduct not found
error_innerUpdate item failed {{.error_info}}
error_innerUpdate item failed {{.error_info}}
error_innerSystem error, please try again later or contact the OpenAPI support team.
error_innerSystem error, please try again later or contact the OpenAPI support team.
error_authThe current item belong to the full FBS or B2C shop, so normal stock must be equal to 0
error_busi_cannot_edit_vskuCan not use OpenAPI to edit/create VSKU, please connect with your manager
error_authYour shop can not use model level dts
error_busiThe merchant/shop has multi warehouse, please input location id
error_paramInvalid parameter for product.
error_system_busyOur system is taking some time to respond, please try later.
error_item_or_variation_not_foundItem or model doesn't exist.
error_seller_under_penaltyThe shop is under penalty.
error_nil_shopid_or_itemidQuery information failed.
error_perm_non_adminDon't have permission.
error_price_exceed_min_limittOriginal_price is less than min price limit.
error_price_exceed_max_limittOriginal_price is bigger than max price limit.
error_wholesale_price_less_than_ratio_limitWholesale price is less than ratio limit.
error_cannt_edit_stock_in_promotionNormal_stock cannot be edited when item is under promotion.
error_cannt_be_no_variation_in_promotionItem cannot be without model when item is under promotion.
error_cannt_delete_option_in_promotionOption of tier_variation cannot be deleted when item is under promotion.
error_cannt_change_tier_variation_in_promotionStructure of tier_variation cannot be edited when item is under promotion.
error_serverInteral error, please contact openapi team.
error_tier_var_too_manyCount of tier_variation is larger than 50.
error_tier_opt_too_manyCount of tier_variation option is larger than 20.
error_tier_opt_val_too_long{{.error_info}}
error_tier_var_name_too_long{{.error_info}}
error_tier_img_partialInteral error, please contact openapi team.
error_tier_img_old_appInteral error, please contact openapi team.
error_tier_img_not_allowerNot allowed to update tier-variation image.
error_in_item_promotion_remove_modelCan't change tier_variation when item is under promotion.
error_price_should_be_same_for_wholesalesAll model price should be the same when the item has been set wholesales.
error_model_tier_index_level_mismatch_var_levelItem tier_index level mismatch tier variation list level.
error_model_count_over_limitThe count of model is too large. Should be under 20 (50 for TW)
error_model_nonempty_itemtier_empty_indexItem tier_index is required.
error_model_duplicate_nameItem tier_variation have duplicate name.
error_model_duplicate_tier_variation_indexItem have duplicate tier_index.
#

§15 Common errors

Common errors

ErrorDescriptionSolution
error_authpartner_id is invalid
error_authThe App is deleted, and you'll be unable to make any API call.
error_authApp developer’s permissions for authorizations have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details.
error_paramThere is no partner_id in query.
error_paramInvalid partner_id.
error_paramno timestamp
error_paramInvalid timestamp
error_paramThere is no sign in query.
error_signWrong sign.
invalid_partner_idInvalid partner_id, please have a check.
error_authNo permission to current api.
error_api_call_restrictedThe App permission for api call have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details.
api_suspendedThe API is offline. Please call v2 API instead.
error_limitThe total API call number made by your APP has reached the daily API call limit, please try again after 00: 00 (UTC+08:00)
error_rate_limitToo many requests. You have reached the rate limit. Please try again later.
source_ip_undeclaredRequest Source IP ({ip}) is undeclared. Please declare all your IP addresses in the Shopee Open Platform Console > App list > IP Address Whitelist
error_paramPermission denied. This API is currently offline or the request path is incorrect.
error_paramPartner_id is invalid, should be an integer between 0 and 4294967295.
error_paramno timestamp.
error_paramTimestamp is invalid, should be an integer between 0 and 4294967295.
error_paramTimestamp is expired.
error_partner_key_expiredYour API partner key has expired, please reset the Live API Partner Key in Console to get a new valid partner key to call open api.
error_api_permissionThis app type has no permission to this API.
error_paramThere is no access_token in query.
error_authInvalid access_token.
error_authInvalid partner_id or shopid.
shop_no_linkedPartner and shop has no linked.
shop_bannedThe shop account has been banned. Permissions for shop authorization and API calls have been suspended until the shop account is restored.
invalid_acceess_tokenInvalid access_token, please have a check.
partner_shop_no_linkInvalid partner_id or shop_id, please have a check.
error_ashop_api_permissionThe shop is Affiliate shop has no permission to call this API.
error_kyc_authNo permission. Please inform the seller to complete the Seller Registration on Shopee Seller Center first, then this shop can call for this API.
error_authSystem error, please try again later.
error_paramThere is no shop_id in query.
error_paramshop_id is invalid, should be an integer between 0 and 4294967295.
#

§16 Update log

Update log

DateChange
2025-09-12The tier_variation structure in the documentation has been deprecated. Please use the standardise_tier_variation structure when uploading variations.
2024-03-26Add standard variation fields
2022-08-11add model list
2022-03-30update image id description
2022-01-27update the define and tier_variation description
#