1. SKU

API URL

post {HTTP(S)host} /api/{version}/sku

Category master data (tree / create / update / delete) is documented in Sku category. Request URL: /api/{version}/sku_category. Create/update SKU still attach categories by categoryName1 / categoryName2 / categoryName3. SKU property and SPU attribute APIs are in SKU property and SPU attribute.

1.1. Query sku List

1.1.1. SERVICE_TYPE

QUERY_SIMPLE_LIST_SKU

1.1.2. Request

SkuCustomFieldValueSO(Custom Field Search)

1.1.3. Reponse

Sku

SubSkuDTO(Sub-product information)

SkuCustomFieldValueVO(Custom Field inf)

SkuSupplierDTO(Supplier information)

Request example:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/sku' \
--form 'appId="TEST"' \
--form 'serviceType="QUERY_SIMPLE_LIST_SKU"' \
--form 'bizParam="{
    \"page\":1,
    \"pageSize\":1
}"' \
--form 'timestamp="1731742317"' \
--form 'sign="a9837b4485a8e427f584933267dc4ea4"'

Response example:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":[{\"cartonVolumeUnit\":\"cm3\",\"ccPriceUnit\":\"USD\",\"customsDeclarationPriceUnit\":\"USD\",\"dangerousTransportGoodsType\":\"NONE\",\"dimensionUnit\":\"cm\",\"enable\":1,\"exportTax\":0.0,\"height\":33.3,\"isDeleted\":0,\"length\":33.3,\"needQualityInspection\":false,\"netWeight\":33.0,\"picUrl\":\"https://test-logo.pomogo.co/STORE/1902244893482377216/default/ced190dda0e74aa0ba25879dffb8b9bc.png\",\"price\":0.0000,\"priceUnit\":\"USD\",\"sku\":\"3WkC2QzAnXPTsGO4vCNUgm\",\"skuCustomFieldValueVOList\":[{\"candidateValue\":[],\"columCode\":1,\"columName\":\"商品有效期\",\"columType\":\"DATE\",\"customFieldId\":17,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":17,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":2,\"columName\":\"商品产地\",\"columType\":\"STRING\",\"customFieldId\":16,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":16,\"isQuery\":1,\"isShow\":1,\"required\":0},{\"candidateValue\":[\"1\",\"2\",\"3\",\"123\"],\"columCode\":3,\"columName\":\"测试单选栏位\",\"columType\":\"SELECT\",\"customFieldId\":47,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":47,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":5,\"columName\":\"货值\",\"columType\":\"DATE\",\"customFieldId\":26,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"id\":26,\"isQuery\":0,\"isShow\":1,\"required\":0},{\"candidateValue\":[],\"columCode\":6,\"columName\":\"产品编码\",\"columType\":\"STRING\",\"customFieldId\":33,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":33,\"isQuery\":1,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":7,\"columName\":\"123\",\"columType\":\"STRING\",\"customFieldId\":40,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":40,\"isQuery\":1,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":10,\"columName\":\"地区账套\",\"columType\":\"STRING\",\"customFieldId\":27,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":27,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":11,\"columName\":\"单箱条码\",\"columType\":\"STRING\",\"customFieldId\":28,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":28,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":12,\"columName\":\"规格型号\",\"columType\":\"STRING\",\"customFieldId\":29,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":29,\"isQuery\":0,\"isShow\":0,\"required\":0}],\"title\":\"yhx母婴商品测试001自营 33\",\"type\":\"SINGLE\",\"weight\":33.0,\"weightUnit\":\"KG\",\"width\":33.3}],\"state\":\"success\",\"total\":3960}",
    "requestId": "afac1414-8397-4657-bd57-ed2c90bdc9b7"
}

1.2. Create sku

1.2.1. SERVICE_TYPE

INSERT_SKU_INFO

1.2.2. Request

SubSkuDTO(Sub sku)

SkuCustomFieldValueVO(Custom Field )

SkuSupplierDTO(Supplier information)

1.2.3. Reponse

Request example:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/sku' \
--form 'appId="TEST"' \
--form 'serviceType="INSERT_SKU_INFO"' \
--form 'bizParam="{
\"sku\":\"ckfsku\",
\"title\":\"ckfsku\",
\"type\":\"SINGLE\",
\"weight\":1,
\"netWeight\":1,
\"weightUnit\":\"KG\",
\"length\":1,
\"width\":1,
\"height\":1,
\"dimensionUnit\":\"cm\",
\"enable\":1,
\"serialEnable\":1,
\"shelfLife\":90,

}"' \
--form 'timestamp="1731742317"' \
--form 'sign="bb8a4a78ebd8b43d6bc71f81e83ae900"'

Response example:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}",
    "requestId": "223f998d-b0d6-43e4-95cb-5c691572417d"
}

1.3. Update sku

1.3.1. SERVICE_TYPE

UPDATE_SKU_INFO

1.3.2. Request

SubSkuDTO(Sub-product information)

SkuCustomFieldValueVO(Custom Field )

SkuSupplierDTO(Supplier information)

1.3.3. Reponse

Request example:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/sku' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--form 'appId="TEST"' \
--form 'serviceType="UPDATE_SKU_INFO"' \
--form 'bizParam="{
\"sku\":\"ckfsku\",
\"title\":\"ckfsku\",
\"type\":\"SINGLE\",
\"weight\":1,
\"netWeight\":1,
\"weightUnit\":\"KG\",
\"length\":1,
\"width\":1,
\"height\":1,
\"dimensionUnit\":\"cm\",
\"enable\":1,
\"serialEnable\":1,
\"shelfLife\":90,

}"' \
--form 'timestamp="1731742317"' \
--form 'sign="f843a75cdb3cf14f403fa423108bc410"'

Response example:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}",
    "requestId": "223f998d-b0d6-43e4-95cb-5c691572417d"
}

1.4. Enables/deactivates the sku

1.4.1. SERVICE_TYPE

UPDATE_SKU_STATUS

1.4.2. Request

1.4.3. Reponse

1.5. QUERY_SYS_SKU

1.5.1. SERVICE_TYPE

QUERY_SYS_SKU_LIST_SKU

1.5.2. Request

SkuExtDTO(SKU query criteria)

1.5.3. Reponse

ReturnSkuExtDTO

SubSkuDTO

1.6. Sku category

API URL

post {HTTP(S)host} /api/{version}/sku_category

Same rules as ERP page Product - Category (/biz/sku_category/): max three levels; name unique under the same parent; update cannot change parent; delete fails if used by system SKU or supplier, and cascades to children. Update/delete require id and version.

Open platform authorization: None of the four APIs are auto-granted. Enable QUERY_SKU_CATEGORY_LIST / CREATE_SKU_CATEGORY / UPDATE_SKU_CATEGORY / DELETE_SKU_CATEGORY for the app on the open platform, or the call returns SERVICE_TYPE_NOT_ALLOW.

Create/update SKU still attach categories by categoryName1 / categoryName2 / categoryName3.

1.6.1. Query sku category tree

SERVICE_TYPE

QUERY_SKU_CATEGORY_LIST

Request

Same as ERP page /biz/sku_category/get_all: full category tree (level-1 nodes with childList). Not a paged query. Do not send page / pageSize. No business filters and no row cap. bizParam may be empty or {}.

Response

SkuCategory

1.6.2. Create sku category

SERVICE_TYPE

CREATE_SKU_CATEGORY

Request

Response

On success result.id is the new category id. Errors match the page, e.g. SKU_CATEGORY_NAME_EXISTS, SKU_CATEGORY_PARENT_NOT_EXISTS, DATA_INPUT_ERROR (more than three levels).

1.6.3. Update sku category

SERVICE_TYPE

UPDATE_SKU_CATEGORY

Request

Cannot change parentId. Version mismatch returns VERSION_DIFF.

1.6.4. Delete sku category

SERVICE_TYPE

DELETE_SKU_CATEGORY

Request

Used by SKU: CATEGORY_USED_BY_SKU. Used by supplier: CATEGORY_USED_BY_SUPPLIER. Children are deleted together.

1.7. SKU property

API URL

post {HTTP(S)host}/api/{version}/skuProperty

SKU properties include unit, brand, sales status, and custom classification. This section does not manage SPU attributes. Text limits: name/nameEN max 50, remark max 128.

1.7.1. Create SKU property

SERVICE_TYPE

CREATE_SKU_PROPERTY

Request

Response

Request example:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/skuProperty' \
--form 'appId="TEST"' \
--form 'serviceType="CREATE_SKU_PROPERTY"' \
--form 'bizParam="{\"type\":\"BRAND\",\"name\":\"Nike\"}"' \
--form 'timestamp="1756865700001"' \
--form 'sign="sign"'

Response example:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":{\"id\":88,\"name\":\"Nike\",\"sequence\":0,\"type\":\"BRAND\"},\"state\":\"success\"}"
}

1.7.2. Update SKU property

SERVICE_TYPE

UPDATE_SKU_PROPERTY

Request

On success, the decoded bizContent is:

{"notSuccess":false,"state":"success"}

1.7.3. Delete SKU property

SERVICE_TYPE

DELETE_SKU_PROPERTY

Request

The success response is the same as update. A missing target or type mismatch returns a business error.

1.7.4. Query SKU property list

SERVICE_TYPE

QUERY_SKU_PROPERTY_LIST

Request

Response

SkuProperty

An empty page returns result=[] and total=0.

Page response example:

{
  "state":"success",
  "errorCode":"",
  "errorMsg":"",
  "bizContent":"{\"notSuccess\":false,\"result\":[{\"id\":88,\"type\":\"BRAND\",\"name\":\"Nike\",\"sequence\":0}],\"state\":\"success\",\"total\":1}"
}

1.7.5. Error response

Validation, duplicate-name, missing-target, and type-mismatch errors are returned inside bizContent. See Error Code.

{
  "state":"success",
  "errorCode":"",
  "errorMsg":"",
  "bizContent":"{\"errorCode\":\"sku.property.type.invalid\",\"errorMsg\":\"Invalid sku property type\",\"notSuccess\":true,\"state\":\"failure\"}"
}

1.8. SPU attribute

API URL

post {HTTP(S) address}/api/{version}/spuAttribute

Manage SPU attribute names and values. Names and values are trimmed, max 50 characters; at most 300 values. An attribute referenced by an SPU cannot be deleted; a referenced name or value cannot be removed or renamed.

1.8.1. Create SPU attribute

SERVICE_TYPE

CREATE_SPU_ATTRIBUTE

Request

Response

Response example:

{
  "state":"success",
  "errorCode":"",
  "errorMsg":"",
  "bizContent":"{\"notSuccess\":false,\"result\":{\"id\":88,\"name\":\"Color\",\"values\":[\"Red\",\"Blue\"]},\"state\":\"success\"}"
}

1.8.2. Update SPU attribute

SERVICE_TYPE

UPDATE_SPU_ATTRIBUTE

Request

On success, decoded bizContent is {"notSuccess":false,"state":"success"}.

1.8.3. Delete SPU attribute

SERVICE_TYPE

DELETE_SPU_ATTRIBUTE

Request

The success response is the same as update. A referenced attribute returns a business error and is not deleted.

1.8.4. Get SPU attribute

SERVICE_TYPE

GET_SPU_ATTRIBUTE

Request

Detail returns id, name, values, and attributeValues with related.

Each attributeValues item contains name, value, and related; related=true means that the value is referenced by an SPU.

1.8.5. Query SPU attribute list

SERVICE_TYPE

QUERY_SPU_ATTRIBUTE_LIST

Request

Empty result is result=[] and total=0. List does not include per-value reference flags; use detail.

A successful list response contains result and total inside bizContent; each result item contains id, name, and values. Failures use the same envelope as SKU property errors.

1.9. SPU Module API

API URL

post {HTTP(S)host}/api/{version}/spu

The current version is v1, and the request URL is /api/v1/spu.

1.9.1. Create system SPU

SERVICE_TYPE

CREATE_SPU

Creates one system SPU per request. You can create new SKUs and link existing SKUs in the same request. Both single-variant and multi-variant products are supported.

The app must be granted separate access to CREATE_SPU; existing permissions for SKU creation or SPU attribute APIs do not grant access to this API. The default rate limit is 50 requests per 60 seconds. The actual quota depends on the app configuration.

Request

All the following parameters are provided in bizParam.

Brands and categories must already exist under the customer associated with the current app. Blank category names are treated as omitted. Specified categories must match their levels and the complete parent-child path. Categories are not created automatically.

If priceUnit, purchaseCostUnit, dimensionUnit, or weightUnit is omitted or null, the system's creation rules apply; an empty string is an invalid enum value. The SPU selling price currency defaults to USD. For newly created SKUs, the selling price and purchase cost currencies default to the customer's effective currency. Shared top-level fields and default rules also apply when linking existing SKUs; see below.

Video (product video)

Attribute (available SPU attributes)

Shared attributes and attribute values are automatically created or supplemented according to the system's creation rules. Internal attribute IDs are not required. Values within the same attribute must be unique. Shared attributes may remain even if SPU creation fails.

AttributeValue (attribute value)

SpuSku (create or link a SKU)

For a newly created SKU, omitted length, width, height, and weight values each default to 1. New SKUs have type SINGLE.

Variant and linking rules:

• Single variant: isMultiAttribute=false, with at most one SKU row. If no SKU is provided, only the SPU is created; no SKU is created automatically. Variant attribute associations are not saved for single-variant products.
• Multiple variants: isMultiAttribute=true or omitted, with at least one SKU row. Each row must contain variant information. Variant combinations must be unique across SKUs, and attribute names must be unique within each row.
• If a SKU uses an attribute whose available values are defined in the SPU, its value must be one of those available values.
• Each SKU row must explicitly specify skuBindMode. If LINK cannot find the SKU, the request fails instead of creating one. The same existing SKU cannot be linked more than once.
• A LINK target must be enabled, must not be associated with another SPU, and must have type SINGLE or ASSEMBLY. An ASSEMBLY SKU whose purchase cost is linked to its component SKUs cannot be linked to an SPU.
• For LINK rows, omitted or null name, image, selling price, purchase cost, dimensions, and weight fields are filled with their original values. Non-null values are used for updates; 0 and empty strings also enter business processing.
• Brand, categories, selling price currency, purchase cost currency, dimension unit, and weight unit all use the top-level parameters and system rules. Omitting these fields does not guarantee that the corresponding fields of an existing SKU remain unchanged. When linking, an omitted selling price currency defaults to USD, and omitted dimension and weight units default to cm and KG. To preserve shared fields, explicitly provide the desired values.
• Variant values and sort order come from the current request and are not filled from the existing SKU's previous variant associations.

Only the business fields listed above participate in creation. Callers cannot specify internal primary keys, tenants, login identities, validation switches, or similar fields. Specify brands and categories by name, and existing SKUs by code.

PriceControl (SKU price control configuration)

RuleConfig (price control rule)

CountryRuleSet (country rule set)

CountryRule (country rule)

DefaultCountryRule (default rule for other countries)

Price control is processed as rule objects. This API does not support partial updates to arbitrary nested fields. skuId is not required.

Response

The API uses a two-layer response. bizContent is a JSON string and must be parsed separately. Success in the outer response only means that protocol processing succeeded; also check bizContent.state to determine whether creation succeeded.

Outer response

Business response (after parsing bizContent)

A successful response does not return result, an SPU ID, or a SKU list. Repeated requests with the same SPU code do not update the original product, and idempotent success is not guaranteed.

Request examples

Multiple variants: create new SKUs and link existing SKUs

In the following bizParam example, the brand and categories must already exist, and existing SKUs must meet the linking requirements above:

{
    "spu": "YF_20261026_01",
    "title": "YF_20261026_01",
    "picUrls":
    [
        "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png",
        "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/MjU5YjMyODMxNTE1MjJmNDUwOTc5YzkxZmI1ZmU4MWI.jpg"
    ],
    "video":
    {
        "videoUrl": "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/video/ZjMyNWMxZmRhNmYwZmI0NDg5ZmYwODk4Y2Q2Y2RmM2M.mp4",
        "videoName": "NzVkMTE0NDNhYzc5YTQ2OTY1NTMxODlmMmZhMzc4MWU=.mp4"
    },
    "priceUnit": "BZD",
    "purchaseCostUnit": "BZD",
    "weightUnit": "KG",
    "dimensionUnit": "cm",
    "details": "%3Cp%3EProduct%20details%3C%2Fp%3E",
    "description": "",
    "isMultiAttribute": true,
    "brandName": "brand",
    "categoryName1": "111",
    "categoryName2": "222",
    "categoryName3": "333",
    "spuAttributes":
    [
        {
            "name": "YF_TEST",
            "attributeValues":
            [
                {
                    "value": "Test 1",
                    "name": "YF_TEST",
                    "sort": 1
                },
                {
                    "value": "Test 2",
                    "name": "YF_TEST",
                    "picUrl": null,
                    "sort": 2
                }
            ]
        },
        {
            "name": "Flavor",
            "attributeValues":
            [
                {
                    "value": "Lemon",
                    "sort": 1
                },
                {
                    "value": "Blueberry",
                    "picUrl": null,
                    "sort": 2
                }
            ]
        }
    ],
    "skus":
    [
        {
            "skuBindMode": "LINK",
            "attributeValueList":
            [
                "Test 1",
                "Lemon"
            ],
            "sku": "YF_20261026_02",
            "title": "YF_20261026_02",
            "sort": 1,
            "priceControlConfig":
            {
                "selfConfig":
                {
                    "enabled": true,
                    "priceMode": "BY_COUNTRY",
                    "countryRules":
                    {
                        "countries":
                        [
                            {
                                "countryCode": "US",
                                "currency": "USD",
                                "minPrice": 100
                            }
                        ],
                        "defaultCountryRule":
                        {
                            "enabled": true,
                            "minPrice": 11,
                            "currency": "BZD"
                        }
                    }
                },
                "distributionConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "BZD"
                }
            }
        },
        {
            "skuBindMode": "LINK",
            "picUrl": null,
            "attributeValueList":
            [
                "Test 2",
                "Blueberry"
            ],
            "sku": "YF_20261026_04",
            "purchaseCost": 2,
            "price": 3,
            "weight": 4,
            "length": 3,
            "width": 4,
            "height": 100,
            "title": "YF_20261026_04",
            "sort": 2
        }
    ]
}

Single variant: create an SPU and one SKU

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/spu' \
--form-string 'appId=TEST' \
--form-string 'serviceType=CREATE_SPU' \
--form-string 'bizParam={"spu":"OPEN-SPU-002","title":"Basic cup","isMultiAttribute":false,"priceUnit":"USD","purchaseCostUnit":"CNY","dimensionUnit":"cm","weightUnit":"KG","skus":[{"skuBindMode":"CREATE","sku":"OPEN-SKU-CUP","title":"Basic cup","price":19.90,"purchaseCost":10.00,"length":10,"width":10,"height":20,"weight":0.3}]}' \
--form-string 'timestamp=1793059200000' \
--form-string 'sign=REPLACE_WITH_SIGNATURE_CALCULATED_FROM_ALL_CURRENT_REQUEST_PARAMETERS'

Replace the example timestamp and signature with actual values. Each --form-string value is the form string received by the server; do not add another pair of enclosing double quotes around the JSON.

Single variant: create only an SPU

bizParam：

{
  "spu": "OPEN-SPU-003",
  "title": "Product awaiting SKU linking",
  "isMultiAttribute": false
}

Response examples

Success:

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}"
}

Business failure (duplicate SPU code):

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"errorCode\":\"spu.number.repeat\",\"errorMsg\":\"Duplicate SPU code\",\"notSuccess\":true,\"state\":\"failure\"}"
}

Protocol failure (signature error):

{
  "state": "failure",
  "errorCode": "SIGNATURE_ERROR",
  "errorMsg": "Signature error"
}

The examples above omit optional troubleshooting fields. Error messages are illustrative only.

Common error codes

Business error codes are case-sensitive. The table below lists the actual error code values returned.

Signature, app authorization, IP allowlist, and rate limit failures are usually returned in the outer response:

If the primary account of the customer associated with the app does not exist or is invalid, the business response returns user.not.exist. Other product, image, and price control errors use the system's existing error codes. For complete definitions, see Error Code.

1.9.2. Update system SPU

SERVICE_TYPE

UPDATE_SPU

Updates one system SPU per request. You can create new SKUs and link existing SKUs in the same request. Both single-variant and multi-variant products are supported.

The app must be granted separate access to UPDATE_SPU; existing permissions for SKU creation or SPU attribute APIs do not grant access to this API. The default rate limit is 50 requests per 60 seconds. The actual quota depends on the app configuration.

Request

All the following parameters are provided in bizParam.

Brands and categories must already exist under the customer associated with the current app. Blank category names are treated as omitted. Specified categories must match their levels and the complete parent-child path. Categories are not created automatically.

If priceUnit, purchaseCostUnit, dimensionUnit, or weightUnit is omitted or null, the system's creation rules apply; an empty string is an invalid enum value. The SPU selling price currency defaults to USD. For newly created SKUs, the selling price and purchase cost currencies default to the customer's effective currency. Shared top-level fields and default rules also apply when linking existing SKUs; see below.

Video (product video)

Attribute (available SPU attributes)

Shared attributes and attribute values are automatically created or supplemented according to the system's creation rules. Internal attribute IDs are not required. Values within the same attribute must be unique. Shared attributes may remain even if SPU creation fails.

AttributeValue (attribute value)

SpuSku (create or link a SKU)

For a newly created SKU, omitted length, width, height, and weight values each default to 1. New SKUs have type SINGLE.

Variant and linking rules:

• Single variant: isMultiAttribute=false, with at most one SKU row. If no SKU is provided, only the SPU is created; no SKU is created automatically. Variant attribute associations are not saved for single-variant products.
• Multiple variants: isMultiAttribute=true or omitted, with at least one SKU row. Each row must contain variant information. Variant combinations must be unique across SKUs, and attribute names must be unique within each row.
• If a SKU uses an attribute whose available values are defined in the SPU, its value must be one of those available values.
• Each SKU row must explicitly specify skuBindMode. If LINK cannot find the SKU, the request fails instead of creating one. The same existing SKU cannot be linked more than once.
• A LINK target must be enabled, must not be associated with another SPU, and must have type SINGLE or ASSEMBLY. An ASSEMBLY SKU whose purchase cost is linked to its component SKUs cannot be linked to an SPU.
• Brand, categories, selling price currency, purchase cost currency, dimension unit, and weight unit all use the top-level parameters and system rules. Omitting these fields does not guarantee that the corresponding fields of an existing SKU remain unchanged. When linking, an omitted selling price currency defaults to USD, and omitted dimension and weight units default to cm and KG. To preserve shared fields, explicitly provide the desired values.
• Variant values and sort order come from the current request and are not filled from the existing SKU's previous variant associations.

Only the business fields listed above participate in creation. Callers cannot specify internal primary keys, tenants, login identities, validation switches, or similar fields. Specify brands and categories by name, and existing SKUs by code.

PriceControl (SKU price control configuration)

RuleConfig (price control rule)

CountryRuleSet (country rule set)

CountryRule (country rule)

DefaultCountryRule (default rule for other countries)

Price control is processed as rule objects. This API does not support partial updates to arbitrary nested fields. skuId is not required.

Response

The API uses a two-layer response. bizContent is a JSON string and must be parsed separately. Success in the outer response only means that protocol processing succeeded; also check bizContent.state to determine whether creation succeeded.

Outer response

Business response (after parsing bizContent)

A successful response does not return result, an SPU ID, or a SKU list. Repeated requests with the same SPU code do not update the original product, and idempotent success is not guaranteed.

Request examples

Multiple variants: create new SKUs and link existing SKUs

In the following bizParam example, the brand and categories must already exist, and existing SKUs must meet the linking requirements above:

{
    "spu": "YF_20261026_01",
    "title": "YF_20261026_011",
    "picUrls":
    [
        "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png"
    ],
    "video":
    {
        "videoUrl": "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/video/ZjMyNWMxZmRhNmYwZmI0NDg5ZmYwODk4Y2Q2Y2RmM2M.mp4",
        "videoName": "NzVkMTE0NDNhYzc5YTQ2OTY1NTMxODlmMmZhMzc4MWU=.mp4"
    },
    "priceUnit": "BZD",
    "purchaseCostUnit": "BZD",
    "weightUnit": "KG",
    "dimensionUnit": "cm",
    "details": "%3Cp%3EProduct%20details%3C%2Fp%3E",
    "isMultiAttribute": true,
    "brandName": "Nanjiren",
    "categoryName1": "2",
    "spuAttributes":
    [
        {
            "name": "YF_TEST",
            "attributeValues":
            [
                {
                    "value": "Test 1",
                    "name": "YF_TEST",
                    "sort": 1
                },
                {
                    "value": "Test 3",
                    "sort": 2
                }
            ]
        },
        {
            "name": "Flavor",
            "attributeValues":
            [
                {
                    "value": "Lemon",
                    "sort": 1
                },
                {
                    "value": "Blueberry",
                    "picUrl": null,
                    "sort": 2
                }
            ]
        }
    ],
    "skus":
    [
        {
            "skuBindMode": "CREATE",
            "attributeValueList":
            [
                "Test 1",
                "Lemon"
            ],
            "sku": "YF_20261029_02",
            "title": "YF_20261029_02",
            "sort": 1,
            "priceControlConfig":
            {
                "selfConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 100,
                    "defaultCurrency": "USD",
                    "countryRules":
                    {
                        "countries":
                        [
                            {
                                "countryCode": "US",
                                "currency": "USD",
                                "minPrice": 100
                            }
                        ],
                        "defaultCountryRule":
                        {
                            "enabled": true,
                            "minPrice": 11,
                            "currency": "BZD"
                        }
                    }
                },
                "distributionConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "BZD"
                }
            }
        },
        {
            "skuBindMode": "LINK",
            "picUrl": null,
            "attributeValueList":
            [
                "Test 3",
                "Blueberry"
            ],
            "sku": "YF_20261026_04",
            "purchaseCost": 2,
            "price": 3,
            "weight": 4,
            "length": 3,
            "width": 4,
            "height": 100,
            "title": "YF_20261026_04",
            "sort": 2,
            "priceControlConfig":
            {
                "selfConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "USD",
                    "countryRules":
                    {
                        "countries":
                        [
                            {
                                "countryCode": "US",
                                "currency": "USD",
                                "minPrice": 100
                            }
                        ],
                        "defaultCountryRule":
                        {
                            "enabled": true,
                            "minPrice": 11,
                            "currency": "BZD"
                        }
                    }
                },
                "distributionConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "BZD"
                }
            }
        }
    ]
}

Response examples

Success:

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}"
}

Business failure (SPU code is required):

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"errorCode\":\"spu.number.repeat\",\"errorMsg\":\"SPU code is required\",\"notSuccess\":true,\"state\":\"failure\"}"
}

Protocol failure (signature error):

{
  "state": "failure",
  "errorCode": "SIGNATURE_ERROR",
  "errorMsg": "Signature error"
}

The examples above omit optional troubleshooting fields. Error messages are illustrative only.

1.9.3. Query system SPU codes

SERVICE_TYPE

QUERY_SPU_CODE

Queries a list of SPU codes based on the query criteria. To retrieve SPU details, call the SPU details API.

Request

All the following parameters are provided in bizParam.

Response

The API uses a two-layer response. bizContent is a JSON string and must be parsed separately. Success in the outer response only means that protocol processing succeeded; also check bizContent.state to determine whether creation succeeded.

Outer response

Business response (after parsing bizContent)

A successful response does not return result, an SPU ID, or a SKU list. Repeated requests with the same SPU code do not update the original product, and idempotent success is not guaranteed.

Request examples

In the following bizParam example, the brand and categories must already exist, and existing SKUs must meet the linking requirements above:

{"page":1,"pageSize":10,"updateTimeFrom":"2026-10-29 00:00:00","updateTimeTo":"2026-10-30 23:59:00","titleList":["YF_20261026_011"]}

Response examples

Success:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":[{\"spu\":\"YF_20261026_01\"}],\"state\":\"success\",\"total\":1,\"traceId\":\"a92f7e5ef3a142af946ac72ae6dca7cc\"}",
    "requestId": "f1c3fcd9-9dce-4e5e-a46b-856c55fe6152"
}

1.9.4. Query system SPU details

SERVICE_TYPE

QUERY_SPU_INFO

Send a POST request to /api/v1/spu. Queries SPU details in batches by SPU code for the customer associated with the app, including brands, categories, variant attributes, linked SKUs, and SKU price control configurations.

Request

The following parameters are provided in bizParam. The common form parameters are appId, serviceType, bizParam, timestamp, and sign.

• This API does not use pagination. Do not provide page or pageSize. Split requests into batches if there are more than 200 items.
• Only SPUs found under the customer associated with the current app are returned. Codes that do not exist or belong to another customer do not produce placeholder records. If none match, the request succeeds with an empty list.
• The result order is not guaranteed to match the input code order. Match results using the spu field.

Response

The API uses a two-layer response. bizContent is a JSON string and must be parsed separately. Success in the outer response means that protocol processing succeeded; also check bizContent.state to determine whether the query succeeded.

Outer response

Business response (after parsing bizContent)

This API does not return a pagination count total or hasMore. The optional fields below may be absent if they are not set.

SpuInfo (SPU details)

VideoInfo (product video)

AttributeInfo (SPU attribute)

AttributeValueInfo (SPU attribute value)

SkuInfo (linked SKU information)

SkuAttributeInfo (SKU variant attribute)

PriceControlInfo (SKU price control configuration)

The fields of RuleConfig, CountryRuleSet, CountryRule, and DefaultCountryRule have the same structures as those defined in "Create system SPU" in this section. The query returns the saved configuration: enabled indicates whether the rule is enabled; priceMode is UNIFIED (unified price control) or BY_COUNTRY (price control by country); defaultMinPrice / defaultCurrency specify the unified minimum price and currency; and countryRules contains country-specific rules and the default rule for other countries. Fields that are not set may be absent.

Request examples

bizParam：

{
  "spuList": ["OPEN-SPU-001", "OPEN-SPU-002"]
}

Complete form request:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/spu' \
--form-string 'appId=TEST' \
--form-string 'serviceType=QUERY_SPU_INFO' \
--form-string 'bizParam={"spuList":["OPEN-SPU-001","OPEN-SPU-002"]}' \
--form-string 'timestamp=1793059200000' \
--form-string 'sign=REPLACE_WITH_SIGNATURE_CALCULATED_FROM_ALL_CURRENT_REQUEST_PARAMETERS'

Replace the example timestamp and signature with actual values. bizParam is a JSON string; do not add another pair of enclosing double quotes.

Response examples

Success (only one SPU matches in this example):

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":[{\"brandName\":\"JJ Exclusive Brand\",\"categoryName1\":\"111\",\"categoryName2\":\"222\",\"categoryName3\":\"333\",\"details\":\"%3Cp%3EProduct%20details%3C/p%3E%20%0A%3Cfigure%20class=%22image%22%3E%20%0A%20%3Cimg%20src=%22https://qianyierp-test.oss.aliyuncs.com/attachment/20261103/image/NjU4ZjU5MzFhN2NmYmM5ZTE4OGQ0YTdiZjZjYjI5MmU.jpg%22%20width=%22432%22%20height=%22268%22%3E%20%0A%3C/figure%3E\",\"dimensionUnit\":\"cm\",\"isMultiAttribute\":true,\"picUrls\":[\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\"],\"priceUnit\":\"BZD\",\"purchaseCostUnit\":\"BZD\",\"skus\":[{\"attributeValues\":[{\"name\":\"YF_TEST\",\"value\":\"Test 3\"},{\"name\":\"Flavor\",\"value\":\"Blueberry\"}],\"categoryName1\":\"111\",\"categoryName2\":\"222\",\"categoryName3\":\"333\",\"dimensionUnit\":\"cm\",\"height\":100.0,\"length\":3.0,\"picUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\",\"price\":3.0000,\"priceControlConfig\":{\"distributionConfig\":{\"countryRules\":{\"countries\":[],\"defaultCountryRule\":{\"enabled\":false}},\"defaultCurrency\":\"BZD\",\"defaultMinPrice\":200.0000,\"enabled\":true,\"priceMode\":\"UNIFIED\"},\"selfConfig\":{\"countryRules\":{\"countries\":[],\"defaultCountryRule\":{\"enabled\":false}},\"defaultCurrency\":\"USD\",\"defaultMinPrice\":200.0000,\"enabled\":true,\"priceMode\":\"UNIFIED\"}},\"priceUnit\":\"BZD\",\"purchaseCost\":2.0000,\"purchaseCostUnit\":\"BZD\",\"sku\":\"YF_20261026_04\",\"title\":\"YF_20261026_04\",\"weight\":4.0,\"weightUnit\":\"KG\",\"width\":4.0}],\"spu\":\"YF_20261026_01\",\"spuAttributes\":[{\"attributeValues\":[{\"name\":\"YF_TEST\",\"picUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\",\"sort\":1,\"value\":\"Test 1\"},{\"name\":\"YF_TEST\",\"picUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\",\"sort\":2,\"value\":\"Test 3\"}],\"name\":\"YF_TEST\",\"values\":[\"Test 1\",\"Test 3\"]},{\"attributeValues\":[{\"name\":\"Flavor\",\"sort\":1,\"value\":\"Lemon\"},{\"name\":\"Flavor\",\"sort\":2,\"value\":\"Blueberry\"}],\"name\":\"Flavor\",\"values\":[\"Lemon\",\"Blueberry\"]}],\"title\":\"YF_20261026_011\",\"video\":{\"videoName\":\"NzVkMTE0NDNhYzc5YTQ2OTY1NTMxODlmMmZhMzc4MWU=.mp4\",\"videoUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/video/ZjMyNWMxZmRhNmYwZmI0NDg5ZmYwODk4Y2Q2Y2RmM2M.mp4\"},\"weightUnit\":\"KG\"}],\"state\":\"success\",\"traceId\":\"c920de9db71e42adb0f3950b58b9eb7c\"}",
    "requestId": "edc11513-1f1c-462c-8844-2eaab89e8a07"
}

No matching SPUs:

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"notSuccess\":false,\"state\":\"success\",\"result\":[]}"
}

Business failure (code list is empty or exceeds 200 items):

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"errorCode\":\"data.input.error.msg\",\"errorMsg\":\"Invalid input parameters: spuList.size: 1-200\",\"notSuccess\":true,\"state\":\"failure\"}"
}

The examples above omit optional troubleshooting fields. Error messages are illustrative only. Protocol failures such as signature, authorization, and rate limit errors use the error codes described in "Create system SPU" in this section.