---
title: "Update a metafield definition"
description: >
  Update a metafield definition for a specific resource, such as products or orders.
doc_type: openapi
doc_category: openapi
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/docs/admin-rest-api/shopline-metafields/metafield-definition/update-a-metafield-definition'
  md: 'https://developer.shopline.com/docs/admin-rest-api/shopline-metafields/metafield-definition/update-a-metafield-definition.md'
---
# Update a metafield definition

Update a metafield definition for a specific resource, such as products or orders. 

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

## Endpoint

```http
PUT /metafield_definition.json
```

## Base URL

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

  * `{handle}`: `handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` .

## Request

### Request Headers

* `Content-Type`

  string (required)

  The field must be set to the fixed value `application/json; charset=utf-8`.

* `Authorization`

  string (required)

   The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. 

### Request Body

* `definition`

  object

  Metafield definition.

  * `access`

    object

    Permission information for the metafield definition.

    * `admin`

      string

      The access permission for the metafield definition. Valid values are:
      - `MERCHANT_READ_WRITE`: Merchants can read and write.
      - `MERCHANT_READ`: Merchants have read-only access.
      - `PUBLIC_READ`: The public has read-only access.
      - `PRIVATE`: Accessible only to the current app.
      - `NONE`: No explicit permission set.             
      
      
      :::tip{title="TIP"}
      When `namespace` uses the `$app:{namespace}` format, this value is valid and the default value is `PRIVATE`.
      :::
      
      
      
      

  * `description`

    string

    The description of the metafield definition.   
    Maximum length: 255

  * `key`

    string

    A unique identifier for a metafield definition within its `namespace`.   
    Only letters, numbers, hyphens, and underscores are supported.     
    Minimum length: 3        
    Maximum length: 30       

  * `name`

    string

    The name of the metafield definition.                          
    Maximum length: 255
    

  * `namespace`

    string

    The namespace of the metafield definition. A metafield definition can be uniquely identified by its `key` and `namespace`.
    Only letters, numbers, hyphens, and underscores are supported.                                         
    Minimum length: 2  
    Maximum length: 50   
    
    :::tip{title="TIP"}
    When `access.admin` is provided, the `namespace` parameter must use the `$app:{namespace}` format.
    :::
    
    
    

  * `owner_resource`

    string

    The type of the resource to which the metafield definition belongs. Valid values are:  
    - `products`: Products 
    - `variants`: Product variants  
    - `collections`: Product collections
    - `customers`: Customers
    - `orders`: Orders
    - `pages`: Pages  
    - `blogs`: Blogs
    - `articles`: Articles
    - `shop`: Store

  * `validations`

    array<object>

    A list of data validation rules for metafields under the metafield definition, used to restrict the values that can be written to a metafield. For complete rule names, supported data types, value formats, and validation methods, refer to [Data Validation Rules](https://developer.shopline.com/docs/apps/metafields/references/data-validation-rules.md).

    * `name`

      string

      The name of the data validation rule. Valid values are predefined. For supported values, refer to [Data Validation Rules](https://developer.shopline.com/docs/apps/metafields/references/data-validation-rules.md).

    * `value`

      string

      The value of the data validation rule.

## Response

### Status Codes

* `200`

  For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en).

* `401`

  

* `429`

  

### Response Headers

* `traceId`

  A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise.

### Response Body

#### 200

* `definition`

  object

  Metafield definition.

  * `access`

    object

    Permission information for the metafield definition.

    * `admin`

      string

      The access permission for the metafield definition. Valid values are:   
      - `MERCHANT_READ_WRITE`: Merchants can read and write.
      - `MERCHANT_READ`: Merchants have read-only access.  
      - `PUBLIC_READ`: The public has read-only access.
      - `PRIVATE`: Accessible only to the current app.
      - `NONE`: No explicit permission set.             
      
        
      
      
      

  * `created_at`

    string

    The date and time when the metafield definition was created. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). 

  * `description`

    string

    The description of the metafield definition. 

  * `id`

    long

    The ID of the metafield definition.

  * `key`

    string

    A unique identifier for a metafield  definition within its `namespace`. Only letters, numbers, hyphens, and underscores are supported. 

  * `name`

    string

    The name of the metafield definition.  

  * `namespace`

    string

    The namespace of the metafield definition.  
    Only letters, numbers, hyphens, and underscores are supported. 

  * `owner_resource`

    string

    The type of the resource to which the metafield definition belongs. Valid values are:  
    - `products`: Products 
    - `variants`: Product variants  
    - `collections`: Product collections
    - `customers`: Customers
    - `orders`: Orders
    - `pages`: Pages  
    - `blogs`: Blogs
    - `articles`: Articles
    - `shop`: Store

  * `type`

    string

    The data type for the metafield definition. Valid values are:     
    - `single_line_text_field`: A single-line text field 
    - `list.single_line_text_field`: Multiple single-line text fields  
    - `multi_line_text_field`: Multi-line text field    
    - `color`: A single color  
    - `list.color`: Multiple colors 
    - `date`: A single date 
    - `list.date`: Multiple dates  
    - `date_time`: A single date and time. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).   
    - `list.date_time`: Multiple dates and times. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). 
    - `url`: A single URL  
    - `list.url`: Multiple URLs  
    - `file_reference`: A single file. Support a PDF or image file within 10 MB. Supported image formats: JPG, JPEG, PNG, and GIF.     
    - `list.file_reference`: Multiple files. Support PDF or image files and each file must be within 10 MB. Supported image formats: JPG, JPEG, PNG, and GIF.   
    - `json`: JSON     
    - `weight`: A single weight with a unit   
    - `list.weight`: Multiple weights with units   
    - `volume`: A single volume with a unit   
    - `list.volume`: Multiple volumes with units   
    - `dimension`: A single size with a unit    
    - `list.dimension`: Multiple sizes with units   
    - `number_integer`: A single integer   
    - `list.number_integer`: Multiple integers   
    - `number_decimal`: A single decimal   
    - `list.number_decimal`: Multiple decimals  
    - `rating`: A single rating    
    - `list.rating`: Multiple ratings 
    - `page_reference`: A single page  
    - `list.page_reference`: Multiple pages   
    - `product_reference`: A single product    
    - `list.product_reference`: Multiple products  
    - `variant_reference`: A single product variant  
    - `list.variant_reference`: Multiple product variants    
    - `collection_reference`: A single product collection  
    - `list.collection_reference`: Multiple product collections     
    - `boolean`: Boolean type. Valid values are `true` and `false`.
    - `money`: Amount with a currency   
    
    For more information about metafields, refer to  [Guide to Using Metafields Feature](https://help.shopline.com/hc/en-001/articles/7095355017113).

  * `updated_at`

    string

    The date and time when the metafield definition was updated. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).

  * `validations`

    array<object>

    A list of data validation rules for metafields under the metafield definition.

    * `name`

      string

      The name of the data validation rule.

    * `value`

      string

      The value of the data validation rule.


#### 401

* `errors`

  string

  Error message. 


#### 429

* `errors`

  string

  Error message. 


## OpenAPI Definition

```json
{
  "tags": [
    "Update a metafield definition"
  ],
  "description": "Update a metafield definition for a specific resource, such as products or orders. ",
  "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| RESOURCE_CONFLICT | 409 | a request conflict with the current state of the target resource. |\n"
  },
  "operationId": "77IgysqE",
  "parameters": [
    {
      "name": "Content-Type",
      "in": "header",
      "description": "The field must be set to the fixed value `application/json; charset=utf-8`.",
      "required": true,
      "schema": {
        "name": "Content-Type",
        "type": "string",
        "example": "application/json; charset=utf-8"
      }
    },
    {
      "name": "Authorization",
      "in": "header",
      "description": " The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ",
      "required": true,
      "style": "string",
      "schema": {
        "name": "Authorization",
        "description": " The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ",
        "type": "string",
        "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
      },
      "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "name": "body",
          "description": "Body location parameters",
          "type": "object",
          "properties": {
            "definition": {
              "name": "definition",
              "description": "Metafield definition.",
              "type": "object",
              "properties": {
                "access": {
                  "name": "access",
                  "description": "Permission information for the metafield definition.",
                  "type": "object",
                  "properties": {
                    "admin": {
                      "name": "admin",
                      "description": "The access permission for the metafield definition. Valid values are:\n- `MERCHANT_READ_WRITE`: Merchants can read and write.\n- `MERCHANT_READ`: Merchants have read-only access.\n- `PUBLIC_READ`: The public has read-only access.\n- `PRIVATE`: Accessible only to the current app.\n- `NONE`: No explicit permission set.             \n\n\n:::tip{title=\"TIP\"}\nWhen `namespace` uses the `$app:{namespace}` format, this value is valid and the default value is `PRIVATE`.\n:::\n\n\n\n",
                      "type": "string"
                    }
                  },
                  "example": {
                    "admin": null
                  }
                },
                "description": {
                  "name": "description",
                  "description": "The description of the metafield definition.   \nMaximum length: 255",
                  "type": "string",
                  "example": "This is the description for the \"new\" Product Care Guidelines metafield"
                },
                "key": {
                  "name": "key",
                  "description": "A unique identifier for a metafield definition within its `namespace`.   \nOnly letters, numbers, hyphens, and underscores are supported.     \nMinimum length: 3        \nMaximum length: 30       ",
                  "type": "string",
                  "example": "key_123"
                },
                "name": {
                  "name": "name",
                  "description": "The name of the metafield definition.                          \nMaximum length: 255\n",
                  "type": "string",
                  "example": "Product Care Guide"
                },
                "namespace": {
                  "name": "namespace",
                  "description": "The namespace of the metafield definition. A metafield definition can be uniquely identified by its `key` and `namespace`.\nOnly letters, numbers, hyphens, and underscores are supported.                                         \nMinimum length: 2  \nMaximum length: 50   \n\n:::tip{title=\"TIP\"}\nWhen `access.admin` is provided, the `namespace` parameter must use the `$app:{namespace}` format.\n:::\n\n\n",
                  "type": "string",
                  "example": "my_fields_11"
                },
                "owner_resource": {
                  "name": "owner_resource",
                  "description": "The type of the resource to which the metafield definition belongs. Valid values are:  \n- `products`: Products \n- `variants`: Product variants  \n- `collections`: Product collections\n- `customers`: Customers\n- `orders`: Orders\n- `pages`: Pages  \n- `blogs`: Blogs\n- `articles`: Articles\n- `shop`: Store",
                  "type": "string",
                  "example": "products"
                },
                "validations": {
                  "name": "validations",
                  "description": "A list of data validation rules for metafields under the metafield definition, used to restrict the values that can be written to a metafield. For complete rule names, supported data types, value formats, and validation methods, refer to [Data Validation Rules](https://developer.shopline.com/docs/apps/metafields/references/data-validation-rules.md).",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "name": "name",
                        "description": "The name of the data validation rule. Valid values are predefined. For supported values, refer to [Data Validation Rules](https://developer.shopline.com/docs/apps/metafields/references/data-validation-rules.md).",
                        "type": "string",
                        "example": "min"
                      },
                      "value": {
                        "name": "value",
                        "description": "The value of the data validation rule.",
                        "type": "string",
                        "example": "3"
                      }
                    },
                    "example": {
                      "name": "min",
                      "value": "3"
                    }
                  }
                }
              },
              "required": [
                "key",
                "namespace",
                "owner_resource"
              ],
              "example": {
                "access": {
                  "admin": null
                },
                "description": "This is the description for the \"new\" Product Care Guidelines metafield",
                "key": "key_123",
                "name": "Product Care Guide",
                "namespace": "my_fields_11",
                "owner_resource": "products",
                "validations": null
              }
            }
          },
          "example": {
            "definition": {
              "access": {
                "admin": null
              },
              "description": "This is the description for the \"new\" Product Care Guidelines metafield",
              "key": "key_123",
              "name": "Product Care Guide",
              "namespace": "my_fields_11",
              "owner_resource": "products",
              "validations": null
            }
          }
        },
        "examples": {
          "Update a metafield definition": {
            "description": "更新元字段定义",
            "value": {
              "definition": {
                "description": "Updated description",
                "key": "size_label",
                "name": "Size label",
                "namespace": "size_fields",
                "owner_resource": "products"
              }
            }
          }
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en).",
      "headers": {
        "traceId": {
          "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise."
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "name": "body",
            "type": "object",
            "properties": {
              "definition": {
                "name": "definition",
                "description": "Metafield definition.",
                "type": "object",
                "properties": {
                  "access": {
                    "name": "access",
                    "description": "Permission information for the metafield definition.",
                    "type": "object",
                    "properties": {
                      "admin": {
                        "name": "admin",
                        "description": "The access permission for the metafield definition. Valid values are:   \n- `MERCHANT_READ_WRITE`: Merchants can read and write.\n- `MERCHANT_READ`: Merchants have read-only access.  \n- `PUBLIC_READ`: The public has read-only access.\n- `PRIVATE`: Accessible only to the current app.\n- `NONE`: No explicit permission set.             \n\n  \n\n\n",
                        "type": "string"
                      }
                    },
                    "example": {
                      "admin": null
                    }
                  },
                  "created_at": {
                    "name": "created_at",
                    "description": "The date and time when the metafield definition was created. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). ",
                    "type": "string"
                  },
                  "description": {
                    "name": "description",
                    "description": "The description of the metafield definition. ",
                    "type": "string"
                  },
                  "id": {
                    "name": "id",
                    "description": "The ID of the metafield definition.",
                    "type": "long"
                  },
                  "key": {
                    "name": "key",
                    "description": "A unique identifier for a metafield  definition within its `namespace`. Only letters, numbers, hyphens, and underscores are supported. ",
                    "type": "string"
                  },
                  "name": {
                    "name": "name",
                    "description": "The name of the metafield definition.  ",
                    "type": "string"
                  },
                  "namespace": {
                    "name": "namespace",
                    "description": "The namespace of the metafield definition.  \nOnly letters, numbers, hyphens, and underscores are supported. ",
                    "type": "string"
                  },
                  "owner_resource": {
                    "name": "owner_resource",
                    "description": "The type of the resource to which the metafield definition belongs. Valid values are:  \n- `products`: Products \n- `variants`: Product variants  \n- `collections`: Product collections\n- `customers`: Customers\n- `orders`: Orders\n- `pages`: Pages  \n- `blogs`: Blogs\n- `articles`: Articles\n- `shop`: Store",
                    "type": "string"
                  },
                  "type": {
                    "name": "type",
                    "description": "The data type for the metafield definition. Valid values are:     \n- `single_line_text_field`: A single-line text field \n- `list.single_line_text_field`: Multiple single-line text fields  \n- `multi_line_text_field`: Multi-line text field    \n- `color`: A single color  \n- `list.color`: Multiple colors \n- `date`: A single date \n- `list.date`: Multiple dates  \n- `date_time`: A single date and time. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).   \n- `list.date_time`: Multiple dates and times. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). \n- `url`: A single URL  \n- `list.url`: Multiple URLs  \n- `file_reference`: A single file. Support a PDF or image file within 10 MB. Supported image formats: JPG, JPEG, PNG, and GIF.     \n- `list.file_reference`: Multiple files. Support PDF or image files and each file must be within 10 MB. Supported image formats: JPG, JPEG, PNG, and GIF.   \n- `json`: JSON     \n- `weight`: A single weight with a unit   \n- `list.weight`: Multiple weights with units   \n- `volume`: A single volume with a unit   \n- `list.volume`: Multiple volumes with units   \n- `dimension`: A single size with a unit    \n- `list.dimension`: Multiple sizes with units   \n- `number_integer`: A single integer   \n- `list.number_integer`: Multiple integers   \n- `number_decimal`: A single decimal   \n- `list.number_decimal`: Multiple decimals  \n- `rating`: A single rating    \n- `list.rating`: Multiple ratings \n- `page_reference`: A single page  \n- `list.page_reference`: Multiple pages   \n- `product_reference`: A single product    \n- `list.product_reference`: Multiple products  \n- `variant_reference`: A single product variant  \n- `list.variant_reference`: Multiple product variants    \n- `collection_reference`: A single product collection  \n- `list.collection_reference`: Multiple product collections     \n- `boolean`: Boolean type. Valid values are `true` and `false`.\n- `money`: Amount with a currency   \n\nFor more information about metafields, refer to  [Guide to Using Metafields Feature](https://help.shopline.com/hc/en-001/articles/7095355017113).",
                    "type": "string"
                  },
                  "updated_at": {
                    "name": "updated_at",
                    "description": "The date and time when the metafield definition was updated. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).",
                    "type": "string"
                  },
                  "validations": {
                    "name": "validations",
                    "description": "A list of data validation rules for metafields under the metafield definition.",
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "name": "name",
                          "description": "The name of the data validation rule.",
                          "type": "string"
                        },
                        "value": {
                          "name": "value",
                          "description": "The value of the data validation rule.",
                          "type": "string"
                        }
                      },
                      "example": {
                        "name": null,
                        "value": null
                      }
                    }
                  }
                },
                "example": {
                  "access": {
                    "admin": null
                  },
                  "created_at": null,
                  "description": null,
                  "id": null,
                  "key": null,
                  "name": null,
                  "namespace": null,
                  "owner_resource": null,
                  "type": null,
                  "updated_at": null,
                  "validations": null
                }
              }
            },
            "example": {
              "definition": {
                "access": {
                  "admin": null
                },
                "created_at": null,
                "description": null,
                "id": null,
                "key": null,
                "name": null,
                "namespace": null,
                "owner_resource": null,
                "type": null,
                "updated_at": null,
                "validations": null
              }
            }
          },
          "examples": {
            "Update a metafield definition": {
              "description": "更新元字段定义",
              "value": {
                "definition": {
                  "access": null,
                  "created_at": "2025-04-15T16:21:03+08:00",
                  "description": "Updated description",
                  "id": 43601019606,
                  "key": "size_label",
                  "name": "Size label",
                  "namespace": "size_fields",
                  "owner_resource": "products",
                  "type": "single_line_text_field",
                  "updated_at": "2025-07-15T16:54:00+08:00",
                  "validations": [
                    {
                      "name": "choices",
                      "value": "[\"S\",\"M\",\"L\",\"XL\"]"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "headers": {
        "traceId": {
          "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise."
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "errors": {
                "description": "Error message. ",
                "type": "string"
              }
            },
            "required": [
              "errors"
            ]
          }
        }
      }
    },
    "429": {
      "headers": {
        "traceId": {
          "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise."
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "errors": {
                "description": "Error message. ",
                "type": "string"
              }
            },
            "required": [
              "errors"
            ]
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": []
    }
  ],
  "method": "put",
  "path": "/metafield_definition.json",
  "servers": [
    {
      "url": "https://{handle}.myshopline.com/admin/openapi",
      "variables": {
        "handle": {
          "default": "openapiceshidianpu",
          "description": "`handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` ."
        }
      }
    }
  ],
  "info": {
    "title": "Update a metafield definition",
    "version": "v20260901"
  }
}
```