Operate metafields in bulk

POST https://{handle}.myshopline.com/admin/openapi/v20260301/metafields_set.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 or update metafields in bulk. If the metafield does not exist, it will be created; if it exists, it will be updated with the new data.
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
  • metafieldsobject[]
    List of metafields.
    Maximum size: 25
  • description string
    Description of the metafield.
    Maximum length: 255
    Example: This is the description for the Product Care Guidelines metafield
  • 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
    Example: product-guide
  • namespace string
    The namespace of the metafield, used to group metafields. A metafield can be uniquely identified by its key and namespace.
    Only letters, numbers, hyphens, and underscores are supported.
    Minimum length: 2
    Maximum length: 50
    Example: my_fields
  • owner_id string
    The ID of the resource to which the metafield belongs. For example, when adding a metafield to product A with an ID of 1605898661, the metafield's owner_id is 1605898661.
    Maximum length: 128
    Example: 16058986610866520712462605
  • owner_resource string
    The type of the resource to which the metafield 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
    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: multi_line_text_field
  • value object
    Data stored in the metafield.
    Regardless of how you define the type of the metafield, SHOPLINE will store it in string format. The maximum length of the converted string is 500000.
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
  • fail_metafieldsobject[]
    List of metafields that failed to be created or updated.
  • errors string
    Error message for the metafield creation or update failure.
  • key string
    A unique identifier for a metafield definition within its namespace. Only letters, numbers, hyphens, and underscores are supported.
    Example: product-guide
  • namespace string
    The namespace of the metafield.
    Example: my_fields
  • owner_id string
    The resource ID to which the metafield belongs.
    Example: 16058986610866520712462605
  • owner_resource string
    The type of the resource to which the metafield belongs. Valid values are:
    • products: products
    • variants: product variants
    • collections: product collections
    • customers: customers
    • orders: orders
    • pages: pages
    • blogs: blogs collections
    • articles: blogs
  • metafieldsobject[]
    List of metafields that were successfully created or updated.
  • created_at string
    The date and time when the metafield was created. Format: ISO 8601.
    Example: 2023-05-31T17:03:43+08:00
  • description string
    Description of the metafield.
    Example: This is the description for the Product Care Guidelines metafield
  • id long
    The ID of the metafield.
    Example: 3152668027083
  • key string
    A unique identifier for a metafield definition within its namespace. Only letters, numbers, hyphens, and underscores are supported.
    Example: product-guide
  • namespace string
    The namespace of the metafield.
    Example: my_fields
  • owner_id string
    The resource ID to which the metafield belongs.
    Example: 16058986610866520712462605
  • owner_resource string
    The type of the resource to which the metafield 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.
    Example: multi_line_text_field
  • updated_at string
    The date and time when the metafield was updated. Format: ISO 8601.
    Example: 2023-05-31T17:03:43+08:00
  • value string
    The data stored in the metafield.
    Example: This is the metafields assignment content
API Explorer
https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301

ParamOptions

— header required

Body

required
{
  "metafields": [
    {
      "description": "This is the description for the Product Care Guidelines metafield",
      "key": "product-guide",
      "namespace": "my_fields",
      "owner_id": "16058986610866520712462605",
      "owner_resource": "products",
      "type": "multi_line_text_field",
      "value": null
    }
  ]
}

Language

curl --request POST \
     --url https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301/metafields_set.json \
     --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw' \
     --header 'Content-Type: application/json; charset=utf-8' \
     --header 'accept: application/json'
Examples
Update metafields in batch
Request
{
  "metafields": [
    {
      "description": "Here is the description for the metafield1.",
      "key": "mfkey-1",
      "namespace": "mftest",
      "owner_id": "16058986610866520712462605",
      "owner_resource": "products",
      "type": "list.number_decimal",
      "value": "[\"0.123\",\"22.33\"]"
    },
    {
      "description": "Here is the description for the metafield2.",
      "key": "mfkey-2",
      "namespace": "mftest",
      "owner_id": "2241475414",
      "owner_resource": "customers",
      "type": "multi_line_text_field",
      "value": "This is the assignment contents for metafields."
    }
  ]
}
Response
{
  "fail_metafields": [],
  "metafields": [
    {
      "created_at": "2025-01-23T10:45:19+08:00",
      "description": "Here is the description for the metafield2.",
      "id": 1813234029606,
      "key": "mfkey-2",
      "namespace": "mftest",
      "owner_id": "2241475414",
      "owner_resource": "customers",
      "type": "multi_line_text_field",
      "updated_at": "2025-02-13T17:10:36+08:00",
      "value": "This is the assignment contents for metafields."
    },
    {
      "created_at": "2025-01-23T10:45:19+08:00",
      "description": "Here is the description for the metafield1.",
      "id": 1813234019606,
      "key": "mfkey-1",
      "namespace": "mftest",
      "owner_id": "16058986610866520712462605",
      "owner_resource": "products",
      "type": "list.number_decimal",
      "updated_at": "2025-02-13T17:10:36+08:00",
      "value": "[\"0.123\",\"22.33\"]"
    }
  ]
}
Was this article helpful to you?
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
Legal
Privacy
Terms
Developer Agreement
LinkedInEmail
LinkedInEmail
© Copyright 2013-2025 SHOPLINE Limited.