POST https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json
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 .
Create a metafield definition for a specific resource, such as products or orders.
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 to obtain the access token, and then pass the obtained token in the Bearer format.
    Example:
    Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA
Request Body
  • definitionobject required
    Metafield definition.
  • accessobject
    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
    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
    Example: This is the description for the Product Care Guide
  • key string required
    A unique identifier for a metafield definition within its namespace.
    Only letters, numbers, hyphens, and underscores are supported.
    Minimum length: 3
    Maximum length: 30
    Example: key_001
  • name string required
    The name of the metafield definition.
    Maximum length: 255
    Example: Product Care Guide
  • namespace string required
    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
    When access.admin is provided, the namespace parameter must use the $app:{namespace} format.
    Example: my_fields
  • owner_resource string required
    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
    Example: products
  • type string required
    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.
    • list.date_time: Multiple dates and times. Format: ISO 8601.
    • 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.
    Example: single_line_text_field
  • validationsobject[]
    A list of data validation rules for metafields under the metafield definition, used to constrain the values allowed to be written to metafields. For complete rule names, supported data types, value formats, and validation methods, refer to Data Validation Rules.
  • name string
    The name of the data validation rule. Valid values are predefined. For supported values, refer to Data Validation Rules.
    Example: min
  • value string
    The value of the data validation rule.
    Example: 3
Status Codes
For the complete list of codes and messages, see Http status code.

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
  • definitionobject
    Metafield definition.
  • accessobject
    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.
  • 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.
  • name string
    The name of the metafield definition.
  • namespace string
    The namespace of the metafield definition.
  • 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.
    • list.date_time: Multiple dates and times. Format: ISO 8601.
    • 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.
  • updated_at string
    The date and time when the metafield definition was updated. Format: ISO 8601.
  • validationsobject[]
    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.
API Explorer
https://openapiceshidianpu.myshopline.com/admin/openapi/v20260901

ParamOptions

— header required

Body

required
{
  "definition": {
    "access": {
      "admin": null
    },
    "description": "This is the description for the Product Care Guide",
    "key": "key_001",
    "name": "Product Care Guide",
    "namespace": "my_fields",
    "owner_resource": "products",
    "type": "single_line_text_field",
    "validations": null
  }
}

Language

curl --request POST \
--url https://openapiceshidianpu.myshopline.com/admin/openapi/v20260901/metafield_definition.json \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'accept: application/json'
Examples
Create a metafield definition
Request
{
"definition": {
"description": "Product size label",
"key": "size_label",
"name": "Size label",
"namespace": "size_fields",
"owner_resource": "products",
"type": "single_line_text_field",
"validations": [
{
"name": "choices",
"value": "[\"S\",\"M\",\"L\",\"XL\"]"
}
]
}
}
Response
{
"definition": {
"access": null,
"created_at": "2025-04-15T16:21:03+08:00",
"description": "Product size label",
"id": 43601019606,
"key": "size_label",
"name": "Size label",
"namespace": "size_fields",
"owner_resource": "products",
"type": "single_line_text_field",
"updated_at": "2025-04-15T16:21:03+08:00",
"validations": [
{
"name": "choices",
"value": "[\"S\",\"M\",\"L\",\"XL\"]"
}
]
}
}
Was this article helpful to you?