Create Metafield

This POST endpoint creates a new metafield definition.

Endpoint

• URL: /api/metafields
• Method: POST

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

Request Body

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

curl --location '<BASE-URL>/metafields' \
--header 'accessToken: <ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "fieldType": "product",
  "label": "Brand Name",
  "description": "The brand of the product",
  "code": "brand_name",
  "allowAdminUpdate": true,
  "displayStorefront": true,
  "displayAdmin": true,
  "hasPredefinedValues": false,
  "displayFilter": true,
  "valueType": "text"
}'

Example 2: Select Field with Predefined Values

curl --location '<BASE-URL>/metafields' \
--header 'accessToken: <ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "fieldType": "product",
  "label": "Material Type",
  "description": "The material used for the product",
  "code": "material_type",
  "allowAdminUpdate": true,
  "displayStorefront": true,
  "displayAdmin": true,
  "hasPredefinedValues": true,
  "displayFilter": true,
  "predefinedValues": ["Cotton", "Polyester", "Wool", "Silk"],
  "valueType": "select"
}'

Example 3: Customer Metafield

curl --location '<BASE-URL>/metafields' \
--header 'accessToken: <ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "fieldType": "customer",
  "label": "Loyalty Tier",
  "description": "Customer loyalty program tier",
  "code": "loyalty_tier",
  "allowAdminUpdate": true,
  "displayStorefront": false,
  "displayAdmin": true,
  "hasPredefinedValues": true,
  "displayFilter": false,
  "predefinedValues": ["Bronze", "Silver", "Gold", "Platinum"],
  "valueType": "select"
}'

Response

• Status Code: 200 OK

Sample Response Body

{
  "success": true,
  "message": "Metafield created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "fieldType": "product",
    "label": "Brand Name",
    "description": "The brand of the product",
    "code": "brand_name",
    "allowAdminUpdate": true,
    "displayStorefront": true,
    "displayAdmin": true,
    "hasPredefinedValues": false,
    "displayFilter": true,
    "predefinedValues": [],
    "valueType": "text",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Success Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful.
message	string	Success message.
data	object	The newly created metafield object.

Error Response

• Status Code: 400 Bad Request

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

Common Error Scenarios

• Duplicate Code: A metafield with the same code and fieldType combination already exists.
• Validation Error: Required fields are missing or invalid data types are 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.
• Missing Predefined Values: When hasPredefinedValues is true and valueType is select, but predefinedValues array is empty.

Important Notes

• The combination of code and fieldType must be unique. Attempting to create a metafield with a duplicate combination will result in an error.
• When hasPredefinedValues is set to true and valueType is select, you must provide a predefinedValues array.
• Boolean fields (allowAdminUpdate, displayStorefront, displayAdmin, hasPredefinedValues, displayFilter) are required and default to false if not specified.
• The code should follow a consistent naming convention (e.g., snake_case) for better organization.
• Once created, the metafield can be used to store custom data for the specified entity type.