---
title: "更新元字段"
description: "更新指定资源下指定 ID 的元字段。"
doc_type: openapi
doc_category: openapi
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafields/resource-metafields/update-a-metafield-for-a-resource'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafields/resource-metafields/update-a-metafield-for-a-resource.md'
---
# 更新元字段

更新指定资源下指定 ID 的元字段。

- **Base URL:** `https://{handle}.myshopline.com/admin/openapi`
- **API Version:** v20260901
- **API Type:** Admin
- **API Protocol:** RESTful

## Endpoint

```http
PUT /:resource/:owner_id/metafields/:id.json
```

## Base URL

* `https://{handle}.myshopline.com/admin/openapi`

  * `{handle}`: `handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。

## Request

### Path Parameters

* `owner_id`

  string (required)

  元字段所归属的资源 ID。例如，商品 A 的 ID  是 `1605898661`，当对商品 A 新增元字段时，此时 `owner_id` 是 `1605898661`。  
  最大长度限制：128

* `resource`

  string (required)

  元字段定义所归属的资源类型。有效枚举值包含：  
  - `products`：商品 
  - `variants`：商品款式  
  - `collections`：商品分类
  - `customers`：客户
  - `orders`：订单
  - `pages`：页面  
  - `blogs`：博客集合
  - `articles`：博客
  - `shop`：店铺

* `id`

  string (required)

  元字段 ID。

### Request Headers

* `Content-Type`

  string (required)

  字段值固定为 `application/json; charset=utf-8`。

* `Authorization`

  string (required)

  资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。

### Request Body

* `metafield`

  object

  元字段信息。  

  * `id`

    long

    元字段 ID。

  * `type`

    string

    元字段支持的数据类型，有效枚举值包含：
    
    - `single_line_text_field`：单个单行文本
    - ` list.single_line_text_field`：多个单行文本
    - `multi_line_text_field`：多行文本
    - `color`：单个颜色
    - `list.color`：多个颜色
    - `date`：单个日期
    - `list.date`：多个日期
    - `date_time`：单个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
    - `list.date_time`：多个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
    - `url`：单个 URL
    - `list.url`：多个 URL
    - `file_reference`：单个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。
    - `list.file_reference`：多个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。
    - `json`：JSON 类型
    - `weight`：单个重量，带单位
    - `list.weight`：多个重量，带单位
    - `volume`：单个体积，带单位
    - `list.volume`：多个体积，带单位
    - `dimension`：单个尺寸，带单位
    - `list.dimension`：多个尺寸，带单位
    - `number_integer`：单个整数
    - `list.number_integer`：多个整数
    - `number_decimal`：单个小数
    - `list.number_decimal`：多个小数
    - `rating`：单个等级
    - `list.rating`：多个等级
    - `page_reference`：单个页面
    - `list.page_reference`：多个页面
    - `product_reference`：单个商品
    - `list.product_reference`：多个商品
    - `variant_reference`：单个商品款式
    - `list.variant_reference`：多个商品款式
    - `collection_reference`：单个商品分类
    - `list.collection_reference`：多个商品分类
    - `boolean`：布尔类型，有效值包括 `true` 和 `false`。
    - `money`：资金，带币种单位    
        
    关于更多元字段信息，参考 [元字段功能使用指南](https://help.shopline.com/hc/zh-cn/articles/7095355017113)。              

  * `value`

    object

    存储在元字段中的数据。无论如何定义元字段的类型，SHOPLINE 均将其转换为字符串格式进行存储，转换后的字符串最大长度限制是 500000。
    

  * `description`

    string

    元字段的描述。  
    最大长度限制：255

## Response

### Status Codes

* `200`

  更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。

* `401`

  

* `429`

  

### Response Headers

* `traceId`

  请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。

### Response Body

#### 200

* `metafield`

  object

  元字段信息。

  * `created_at`

    string

    元字段创建的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。

  * `description`

    string

    元字段的描述。  

  * `id`

    long

    元字段 ID。

  * `key`

    string

    元字段定义在其 `namespace` 下的唯一标识符。

  * `namespace`

    string

    元字段的命名空间。

  * `updated_at`

    string

    元字段更新的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。

  * `owner_id`

    string

    元字段所归属的资源 ID。

  * `owner_resource`

    string

    元字段定义所归属的资源类型。有效枚举值包含：  
    - `products`：商品 
    - `variants`：商品款式  
    - `collections`：商品分类
    - `customers`：客户
    - `orders`：订单
    - `pages`：页面  
    - `blogs`：博客集合
    - `articles`：博客
    - `shop`：店铺

  * `type`

    string

    元字段支持的数据类型，有效枚举值包含：
    
    - `single_line_text_field`：单个单行文本
    - ` list.single_line_text_field`：多个单行文本
    - `multi_line_text_field`：多行文本
    - `color`：单个颜色
    - `list.color`：多个颜色
    - `date`：单个日期
    - `list.date`：多个日期
    - `date_time`：单个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
    - `list.date_time`：多个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
    - `url`：单个 URL
    - `list.url`：多个 URL
    - `file_reference`：单个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。
    - `list.file_reference`：多个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。
    - `json`：JSON 类型
    - `weight`：单个重量，带单位
    - `list.weight`：多个重量，带单位
    - `volume`：单个体积，带单位
    - `list.volume`：多个体积，带单位
    - `dimension`：单个尺寸，带单位
    - `list.dimension`：多个尺寸，带单位
    - `number_integer`：单个整数
    - `list.number_integer`：多个整数
    - `number_decimal`：单个小数
    - `list.number_decimal`：多个小数
    - `rating`：单个等级
    - `list.rating`：多个等级
    - `page_reference`：单个页面
    - `list.page_reference`：多个页面
    - `product_reference`：单个商品
    - `list.product_reference`：多个商品
    - `variant_reference`：单个商品款式
    - `list.variant_reference`：多个商品款式
    - `collection_reference`：单个商品分类
    - `list.collection_reference`：多个商品分类
    - `boolean`：布尔类型，有效值包括 `true` 和 `false`。
    - `money`：资金，带币种单位    
        
    关于更多元字段信息，参考 [元字段功能使用指南](https://help.shopline.com/hc/zh-cn/articles/7095355017113)。              

  * `value`

    object

    存储在元字段中的数据。


#### 401

* `errors`

  string

  错误描述。


#### 429

* `errors`

  string

  错误描述。


## OpenAPI Definition

```json
{
  "tags": [
    "更新元字段"
  ],
  "description": "更新指定资源下指定 ID 的元字段。",
  "externalDocs": {
    "url": "",
    "errorTableDescription": "| Error Code | HTTP Status Code | Error Description |\n|------------|------------------|-------------------|\n| DATA_NOT_EXIST | 404 | The requested data does not exist. |\n| INTERNAL_ERROR | 500 | An internal error occured. |\n| INVALID_PARAMETER | 400 | The provided parameter is invalid. |\n| SUCCESS | 200 | request success |\n"
  },
  "operationId": "nWhOmpKg",
  "parameters": [
    {
      "name": "owner_id",
      "in": "path",
      "description": "元字段所归属的资源 ID。例如，商品 A 的 ID  是 `1605898661`，当对商品 A 新增元字段时，此时 `owner_id` 是 `1605898661`。  \n最大长度限制：128",
      "required": true,
      "style": "simple",
      "schema": {
        "name": "owner_id",
        "description": "元字段所归属的资源 ID。例如，商品 A 的 ID  是 `1605898661`，当对商品 A 新增元字段时，此时 `owner_id` 是 `1605898661`。  \n最大长度限制：128",
        "type": "string",
        "example": "16015223514512351000"
      },
      "example": "16015223514512351000",
      "examples": {
        "更新元字段": {
          "value": ""
        }
      }
    },
    {
      "name": "resource",
      "in": "path",
      "description": "元字段定义所归属的资源类型。有效枚举值包含：  \n- `products`：商品 \n- `variants`：商品款式  \n- `collections`：商品分类\n- `customers`：客户\n- `orders`：订单\n- `pages`：页面  \n- `blogs`：博客集合\n- `articles`：博客\n- `shop`：店铺",
      "required": true,
      "style": "simple",
      "schema": {
        "name": "resource",
        "description": "元字段定义所归属的资源类型。有效枚举值包含：  \n- `products`：商品 \n- `variants`：商品款式  \n- `collections`：商品分类\n- `customers`：客户\n- `orders`：订单\n- `pages`：页面  \n- `blogs`：博客集合\n- `articles`：博客\n- `shop`：店铺",
        "type": "string",
        "example": "products"
      },
      "example": "products",
      "examples": {
        "更新元字段": {
          "value": ""
        }
      }
    },
    {
      "name": "id",
      "in": "path",
      "description": "元字段 ID。",
      "required": true,
      "style": "simple",
      "schema": {
        "name": "id",
        "description": "元字段 ID。",
        "type": "string",
        "example": 397923258691
      },
      "example": 397923258691,
      "examples": {
        "更新元字段": {
          "value": ""
        }
      }
    },
    {
      "name": "Content-Type",
      "in": "header",
      "description": "字段值固定为 `application/json; charset=utf-8`。",
      "required": true,
      "schema": {
        "name": "Content-Type",
        "type": "string",
        "example": "application/json; charset=utf-8"
      }
    },
    {
      "name": "Authorization",
      "in": "header",
      "description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。",
      "required": true,
      "style": "string",
      "schema": {
        "name": "Authorization",
        "description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。",
        "type": "string",
        "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
      },
      "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "name": "body",
          "description": "body位置参数",
          "type": "object",
          "properties": {
            "metafield": {
              "name": "metafield",
              "description": "元字段信息。  ",
              "type": "object",
              "properties": {
                "id": {
                  "name": "id",
                  "description": "元字段 ID。",
                  "type": "long",
                  "example": 397923258691
                },
                "type": {
                  "name": "type",
                  "description": "元字段支持的数据类型，有效枚举值包含：\n\n- `single_line_text_field`：单个单行文本\n- ` list.single_line_text_field`：多个单行文本\n- `multi_line_text_field`：多行文本\n- `color`：单个颜色\n- `list.color`：多个颜色\n- `date`：单个日期\n- `list.date`：多个日期\n- `date_time`：单个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。\n- `list.date_time`：多个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。\n- `url`：单个 URL\n- `list.url`：多个 URL\n- `file_reference`：单个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。\n- `list.file_reference`：多个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。\n- `json`：JSON 类型\n- `weight`：单个重量，带单位\n- `list.weight`：多个重量，带单位\n- `volume`：单个体积，带单位\n- `list.volume`：多个体积，带单位\n- `dimension`：单个尺寸，带单位\n- `list.dimension`：多个尺寸，带单位\n- `number_integer`：单个整数\n- `list.number_integer`：多个整数\n- `number_decimal`：单个小数\n- `list.number_decimal`：多个小数\n- `rating`：单个等级\n- `list.rating`：多个等级\n- `page_reference`：单个页面\n- `list.page_reference`：多个页面\n- `product_reference`：单个商品\n- `list.product_reference`：多个商品\n- `variant_reference`：单个商品款式\n- `list.variant_reference`：多个商品款式\n- `collection_reference`：单个商品分类\n- `list.collection_reference`：多个商品分类\n- `boolean`：布尔类型，有效值包括 `true` 和 `false`。\n- `money`：资金，带币种单位    \n    \n关于更多元字段信息，参考 [元字段功能使用指南](https://help.shopline.com/hc/zh-cn/articles/7095355017113)。              ",
                  "type": "string",
                  "example": "single_line_text_field"
                },
                "value": {
                  "name": "value",
                  "description": "存储在元字段中的数据。无论如何定义元字段的类型，SHOPLINE 均将其转换为字符串格式进行存储，转换后的字符串最大长度限制是 500000。\n",
                  "type": "object",
                  "example": {}
                },
                "description": {
                  "name": "description",
                  "description": "元字段的描述。  \n最大长度限制：255",
                  "type": "string",
                  "example": "My fields"
                }
              },
              "required": [
                "id",
                "type",
                "value"
              ],
              "example": {
                "type": "single_line_text_field",
                "value": {},
                "description": "My fields",
                "id": 397923258691
              }
            }
          },
          "required": [
            "metafield"
          ],
          "example": {
            "metafield": {
              "description": "My fields",
              "id": 397923258691,
              "type": "single_line_text_field",
              "value": {}
            }
          }
        },
        "examples": {
          "更新元字段": {
            "description": "更新元字段",
            "value": {
              "metafield": {
                "id": 1782269169606,
                "type": "single_line_text_field",
                "value": "A product title",
                "description": "update"
              }
            }
          }
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。",
      "headers": {
        "traceId": {
          "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "name": "body",
            "type": "object",
            "properties": {
              "metafield": {
                "name": "metafield",
                "description": "元字段信息。",
                "type": "object",
                "properties": {
                  "created_at": {
                    "name": "created_at",
                    "description": "元字段创建的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。",
                    "type": "string"
                  },
                  "description": {
                    "name": "description",
                    "description": "元字段的描述。  ",
                    "type": "string"
                  },
                  "id": {
                    "name": "id",
                    "description": "元字段 ID。",
                    "type": "long"
                  },
                  "key": {
                    "name": "key",
                    "description": "元字段定义在其 `namespace` 下的唯一标识符。",
                    "type": "string"
                  },
                  "namespace": {
                    "name": "namespace",
                    "description": "元字段的命名空间。",
                    "type": "string"
                  },
                  "updated_at": {
                    "name": "updated_at",
                    "description": "元字段更新的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。",
                    "type": "string"
                  },
                  "owner_id": {
                    "name": "owner_id",
                    "description": "元字段所归属的资源 ID。",
                    "type": "string"
                  },
                  "owner_resource": {
                    "name": "owner_resource",
                    "description": "元字段定义所归属的资源类型。有效枚举值包含：  \n- `products`：商品 \n- `variants`：商品款式  \n- `collections`：商品分类\n- `customers`：客户\n- `orders`：订单\n- `pages`：页面  \n- `blogs`：博客集合\n- `articles`：博客\n- `shop`：店铺",
                    "type": "string"
                  },
                  "type": {
                    "name": "type",
                    "description": "元字段支持的数据类型，有效枚举值包含：\n\n- `single_line_text_field`：单个单行文本\n- ` list.single_line_text_field`：多个单行文本\n- `multi_line_text_field`：多行文本\n- `color`：单个颜色\n- `list.color`：多个颜色\n- `date`：单个日期\n- `list.date`：多个日期\n- `date_time`：单个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。\n- `list.date_time`：多个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。\n- `url`：单个 URL\n- `list.url`：多个 URL\n- `file_reference`：单个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。\n- `list.file_reference`：多个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。\n- `json`：JSON 类型\n- `weight`：单个重量，带单位\n- `list.weight`：多个重量，带单位\n- `volume`：单个体积，带单位\n- `list.volume`：多个体积，带单位\n- `dimension`：单个尺寸，带单位\n- `list.dimension`：多个尺寸，带单位\n- `number_integer`：单个整数\n- `list.number_integer`：多个整数\n- `number_decimal`：单个小数\n- `list.number_decimal`：多个小数\n- `rating`：单个等级\n- `list.rating`：多个等级\n- `page_reference`：单个页面\n- `list.page_reference`：多个页面\n- `product_reference`：单个商品\n- `list.product_reference`：多个商品\n- `variant_reference`：单个商品款式\n- `list.variant_reference`：多个商品款式\n- `collection_reference`：单个商品分类\n- `list.collection_reference`：多个商品分类\n- `boolean`：布尔类型，有效值包括 `true` 和 `false`。\n- `money`：资金，带币种单位    \n    \n关于更多元字段信息，参考 [元字段功能使用指南](https://help.shopline.com/hc/zh-cn/articles/7095355017113)。              ",
                    "type": "string"
                  },
                  "value": {
                    "name": "value",
                    "description": "存储在元字段中的数据。",
                    "type": "object"
                  }
                },
                "example": {
                  "key": null,
                  "namespace": null,
                  "owner_id": null,
                  "updated_at": null,
                  "value": null,
                  "created_at": null,
                  "description": null,
                  "id": null,
                  "owner_resource": null,
                  "type": null
                }
              }
            },
            "example": {
              "metafield": {
                "created_at": null,
                "description": null,
                "id": null,
                "key": null,
                "type": null,
                "updated_at": null,
                "namespace": null,
                "owner_id": null,
                "owner_resource": null,
                "value": null
              }
            }
          },
          "examples": {
            "更新元字段": {
              "description": "更新元字段",
              "value": {
                "metafield": {
                  "namespace": "seo",
                  "owner_id": "16068033970754864233492340",
                  "created_at": "2025-01-03T02:22:55+08:00",
                  "description": "update",
                  "id": 1782269169606,
                  "owner_resource": "products",
                  "type": "single_line_text_field",
                  "updated_at": "2025-07-15T19:11:11+08:00",
                  "value": "A product title",
                  "key": "seoTitle"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "headers": {
        "traceId": {
          "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "errors": {
                "description": "错误描述。",
                "type": "string"
              }
            },
            "required": [
              "errors"
            ]
          }
        }
      }
    },
    "429": {
      "headers": {
        "traceId": {
          "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "errors": {
                "description": "错误描述。",
                "type": "string"
              }
            },
            "required": [
              "errors"
            ]
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": []
    }
  ],
  "method": "put",
  "path": "/:resource/:owner_id/metafields/:id.json",
  "servers": [
    {
      "url": "https://{handle}.myshopline.com/admin/openapi",
      "variables": {
        "handle": {
          "default": "openapiceshidianpu",
          "description": "`handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。"
        }
      }
    }
  ],
  "info": {
    "title": "更新元字段",
    "version": "v20260901"
  }
}
```