Create a metafield definition

POST https://{handle}.myshopline.com/admin/openapi/v20260301/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 eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw
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.
    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 collections
    • articles: blogs
    • 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
    • customer_reference: A single customer
    • list.customer_reference: Multiple customers
    • order_reference: A single order
    • list.order_reference: Multiple orders
    • 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
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 string
    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 collections
    • articles: blogs
    • 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
    • customer_reference: A single customer
    • list.customer_reference: Multiple customers
    • order_reference: A single order
    • list.order_reference: Multiple orders
    • 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.
API Explorer
https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301

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"
  }
}

Language

curl --request POST \
     --url https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301/metafield_definition.json \
     --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw' \
     --header 'Content-Type: application/json; charset=utf-8' \
     --header 'accept: application/json'
Examples
Create a metafield definition
Request
{
  "definition": {
    "access": {},
    "description": "This is the description for the Product Care Guidelines metafield",
    "key": "product-guide1",
    "name": "Product Care Guide",
    "namespace": "my_fields1",
    "owner_resource": "products",
    "type": "multi_line_text_field"
  }
}
Response
{
  "definition": {
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "description": "This is the description for the Product Care Guidelines metafield",
    "id": 43601019606,
    "key": "product-guide1",
    "name": "Product Care Guide",
    "namespace": "my_fields1",
    "owner_resource": "products",
    "type": "multi_line_text_field",
    "updated_at": "2025-04-15T16:21:03+08:00"
  }
}
Was this article helpful to you?
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
Legal
Privacy
Terms
Developer Agreement
LinkedInEmail
LinkedInEmail
© Copyright 2013-2025 SHOPLINE Limited.