Get Global Attributes

GET

/product/202309/categories/{category_id}/global_attributes

Retrieve the standard built-in product and sales attributes for listing a global product in a particular category across the seller’s markets. Products on TikTok Shop are grouped into categories predefined by TikTok Shop, and each category is associated with a standard set of product attributes and sales attributes.

Sales attributes (e.g. size, color, length) define product variants and are optional if your product is straightforward and has no variants.
Product attributes (e.g. manufacturer, country of origin, materials used) describe the product as a whole, regardless of variant. Some product attributes are mandatory based on listing policies. Use this API to determine the mandatory and optional attributes, including market-specific requirements, before listing a global product. Note: It must be a leaf category that corresponds to the category tree type specified in the category_version property.

Authorizations

accessToken

Parameters

Path Parameters

category_id

required

string

The ID of the category. It must be a leaf category.

Query Parameters

locale

string

Allowed values: cs-CZ de-AT de-BE de-DE el-GR en-GB en-IE en-US es-ES es-MX fr-FR fr-BE hu-HU id-ID it-IT ja-JP ms-MY nl-NL nl-BE pl-PL pt-BR pt-PT th-TH vi-VN zh-CN

The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values:

cs-CZ
de-AT
de-BE
de-DE
el-GR
en-GB
en-IE
en-US
es-ES
es-MX
fr-FR
fr-BE
hu-HU
id-ID
it-IT
ja-JP
ms-MY
nl-NL
nl-BE
pl-PL
pt-BR
pt-PT
th-TH
vi-VN
zh-CN

category_version

string

Filter categories by the category tree version.Possible values based on region:

US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API.
Other regions: v1, represents the 3-level category tree.Default: v1

Responses

200

Success

application/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

attributes

The list of standard built-in product and sales attributes that are bound to the specified category.

Array<object>

object

The ID of the built-in attribute.

string

name

The name of the built-in attribute.

string

type

The attribute type. Possible values:

SALES_PROPERTY: Indicates sales attributes that define product variants.
PRODUCT_PROPERTY: Indicates product attributes that describe the product as a whole.

string

Allowed values: SALES_PROPERTY PRODUCT_PROPERTY

is_requried

A flag indicating whether the product attribute is required across all of the seller’s markets when creating or editing a product.

true: The attribute is required in all of the seller’s markets.
false: The attribute is not required in all of the seller’s markets; it may be required in some markets, required only under certain conditions, or optional. Refer to required_regions, optional_regions, and requirement_conditions for the specific requirements.

Applicable only if type=PRODUCT_PROPERTY.

boolean

values

A list of selectable values for the attribute.

Array<object>

object

The ID of the built-in attribute value.

string

name

The name of the built-in attribute value.

string

is_multiple_selection

A flag to indicate if multiple values can be provided for the attribute when creating or editing a product.

boolean

is_customizable

A flag to indicate if the attribute value can be customized by sellers when creating or editing a product.

boolean

requirement_conditions

A list of market-specific conditions that determine whether the product attribute is required based on the seller’s inputs for other attributes. If any condition for a market is met, the attribute is required in that market; otherwise, it is optional in that market. This field is omitted when no conditions apply.

For example, a condition can state that the “Battery type” attribute is required if the seller selects the value “Batteries” for the attribute “Contains Batteries or Cells?”. For more scenario-based guidance on using this parameter, refer to the Solution Guide.

Applicable only if type=PRODUCT_PROPERTY and optional_regions is not empty.

Array<object>

object

region

The market where the attribute is required when the conditions are met. Possible values:

AT: Austria
BE: Belgium
CZ: Czech Republic
DE: Germany
ES: Spain
FR: France
GB: United Kingdom
GR: Greece
HU: Hungary
ID: Indonesia
IT: Italy
IE: Ireland
JP: Japan
MY: Malaysia
NL: Netherlands
PH: Philippines
PL: Poland
PT: Portugal
SG: Singapore
TH: Thailand
US: United States
VN: Vietnam
MX: Mexico

string

Allowed values: AT BE CZ DE ES FR GB GR HU ID IT IE JP MY NL PH PL PT SG TH US VN MX

condition_type

The type of condition. Possible values:

VALUE_ID_MATCH: The condition is true when the seller selects a value whose ID matches the one specified in this condition.

string

Allowed values: VALUE_ID_MATCH

attribute_id

The ID of the product attribute that is being evaluated by the condition.

string

attribute_value_id

The ID of the product attribute value that must match the seller’s input for the condition to be true.

string

optional_regions

The markets where the attribute is purely optional, or required only under certain conditions. Refer to requirement_conditions for details on markets with conditional requirements. This field is omitted when there are no optional markets.

Possible values:

AT: Austria
BE: Belgium
CZ: Czech Republic
DE: Germany
ES: Spain
FR: France
GB: United Kingdom
GR: Greece
HU: Hungary
ID: Indonesia
IT: Italy
IE: Ireland
JP: Japan
MY: Malaysia
NL: Netherlands
PH: Philippines
PL: Poland
PT: Portugal
SG: Singapore
TH: Thailand
US: United States
VN: Vietnam
MX: Mexico Applicable only if is_requried=false.

Array<string>

Allowed values: AT BE CZ DE ES FR GB GR HU ID IT IE JP MY NL PH PL PT SG TH US VN MX

required_regions

The markets where the attribute is required without conditions. When is_requried=true, this list contains all of the seller’s markets. When is_requried=false, it contains only the markets where the attribute is unconditionally required. This field is omitted when there are no unconditionally required markets.

Possible values:

AT: Austria
BE: Belgium
CZ: Czech Republic
DE: Germany
ES: Spain
FR: France
GB: United Kingdom
GR: Greece
HU: Hungary
ID: Indonesia
IT: Italy
IE: Ireland
JP: Japan
MY: Malaysia
NL: Netherlands
PH: Philippines
PL: Poland
PT: Portugal
SG: Singapore
TH: Thailand
US: United States
VN: Vietnam
MX: Mexico

Array<string>

Allowed values: AT BE CZ DE ES FR GB GR HU ID IT IE JP MY NL PH PL PT SG TH US VN MX

Example

{
  "code": 0,
  "data": {
    "attributes": [
      {
        "id": "100392",
        "name": "Occasion",
        "type": "PRODUCT_PROPERTY",
        "is_requried": false,
        "values": [
          {
            "id": "1001533",
            "name": "Birthday"
          }
        ],
        "is_multiple_selection": false,
        "is_customizable": false,
        "requirement_conditions": [
          {
            "region": "IE",
            "condition_type": "VALUE_ID_MATCH",
            "attribute_id": "101610",
            "attribute_value_id": "1024358"
          }
        ],
        "optional_regions": [
          "US"
        ],
        "required_regions": [
          "GB",
          "MY",
          "PH",
          "SG",
          "TH",
          "VN"
        ]
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Get Global Attributes

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Example

Start here

SDKs

OpenAPI