Update Metafield

This PUT endpoint updates an existing metafield definition by its ID.

Endpoint

• URL: /api/metafields/:id
• Method: PUT

Authentication

• Header: accessToken
• Type: Bearer Token
• Value: <ACCESS-TOKEN>

Request Headers

Header	Type	Description
accessToken	string	Access token for authentication. (required)
Content-Type	string	Must be application/json

Path Parameters

Parameter	Type	Description
id	string	The unique identifier of the metafield to update. (required)

Request Body

All fields are optional. Only include the fields you want to update.

Field	Type	Description
fieldType	string	The entity type this metafield applies to. See supported field types below.
label	string	Display label for the metafield.
description	string	Description of the metafield's purpose.
code	string	Unique code identifier. Must be unique in combination with fieldType.
allowAdminUpdate	boolean	Whether admin can update this field.
displayStorefront	boolean	Whether this field is visible on storefront.
displayAdmin	boolean	Whether this field is visible in admin panel.
hasPredefinedValues	boolean	Whether this field has predefined values.
displayFilter	boolean	Whether this field can be used as a filter.
predefinedValues	array	Array of predefined values. Required if hasPredefinedValues is true and valueType is select.
valueType	string	Data type of the metafield value. See supported value types below.

Supported Field Types

• customer
• company
• shippingAddress
• billingAddress
• category
• product
• variant
• order
• invoice
• salesRep
• shippingMethod

Supported Value Types

• text - Plain text string
• number - Numeric value
• file - File upload
• json - JSON object
• select - Single selection from predefined values
• dateTime - Date and time
• boolean - True/false value
• product - Product reference
• multi-text - Multiple text values
• range - Numeric range
• html-markdown - HTML or Markdown content
• numberRange - Numeric range with min/max

Sample Request

Example 1: Update Label and Description

curl --location --request PUT '<BASE-URL>/metafields/507f1f77bcf86cd799439011' \
--header 'accessToken: <ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "label": "Product Brand",
  "description": "Official brand name of the product"
}'

Example 2: Update Display Settings

curl --location --request PUT '<BASE-URL>/metafields/507f1f77bcf86cd799439011' \
--header 'accessToken: <ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "displayStorefront": false,
  "displayAdmin": true,
  "displayFilter": false
}'

Example 3: Add Predefined Values

curl --location --request PUT '<BASE-URL>/metafields/507f1f77bcf86cd799439012' \
--header 'accessToken: <ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "hasPredefinedValues": true,
  "predefinedValues": ["Small", "Medium", "Large", "X-Large"],
  "valueType": "select"
}'

Example 4: Complete Update

curl --location --request PUT '<BASE-URL>/metafields/507f1f77bcf86cd799439011' \
--header 'accessToken: <ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "label": "Product Category",
  "description": "Primary category of the product",
  "allowAdminUpdate": true,
  "displayStorefront": true,
  "displayAdmin": true,
  "hasPredefinedValues": true,
  "displayFilter": true,
  "predefinedValues": ["Electronics", "Clothing", "Home & Garden", "Sports"],
  "valueType": "select"
}'

Response

• Status Code: 200 OK

Sample Response Body

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "fieldType": "product",
    "label": "Product Brand",
    "description": "Official brand name of the product",
    "code": "brand_name",
    "allowAdminUpdate": true,
    "displayStorefront": false,
    "displayAdmin": true,
    "hasPredefinedValues": false,
    "displayFilter": false,
    "predefinedValues": [],
    "valueType": "text",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:45:00.000Z"
  }
}

Success Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful.
data	object	The updated metafield object with all fields.

Error Response

• Status Code: 400 Bad Request

{
  "success": false,
  "message": "Error message describing what went wrong"
}

Common Error Scenarios

• Metafield Not Found: No metafield exists with the provided ID.
• Duplicate Code: Attempting to update code or fieldType to a combination that already exists.
• Validation Error: Invalid data types or values provided.
• Invalid Field Type: The fieldType value is not in the supported list.
• Invalid Value Type: The valueType value is not in the supported list.
• Unauthorized Access: Missing or invalid access token.

Important Notes

• Only the fields included in the request body will be updated. All other fields will remain unchanged.
• If you change hasPredefinedValues to true and valueType to select, ensure you also provide the predefinedValues array.
• Changing the code or fieldType may affect existing data associated with this metafield. Exercise caution when updating these fields.
• The updatedAt timestamp will be automatically updated to reflect the time of the modification.
• Partial updates are supported - you don't need to send all fields, only those you want to modify.