Get All Metafields

This GET endpoint retrieves a list of all metafields with support for filtering and pagination.

Endpoint

• URL: /api/metafields
• Method: GET

Authentication

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

Request Headers

Header	Type	Description
accessToken	string	Access token for authentication. (required)

Query Parameters

Parameter	Type	Description
page	number	The page number to retrieve. Defaults to 1 if not specified.
limit	number	The maximum number of items to return per page. Defaults to 10 if not specified. Max is 50.
id	string	Filter for a specific metafield by its unique ID.
id:in	string	Filter for multiple metafields by a comma-separated list of IDs.
code	string	Filter by the metafield's unique code.
code:in	string	Filter for multiple metafields by a comma-separated list of codes.
type	string	Filter by field type (e.g., customer, company, product, order).
type:in	string	Filter for multiple metafields by a comma-separated list of field types.

Supported Field Types

The type and type:in parameters accept the following values:

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

Sample Request

curl --location '<BASE-URL>/metafields?page=1&limit=10&type=product' \
--header 'accessToken: <ACCESS-TOKEN>'

Response

• Status Code: 200 OK

Sample Response Body

{
  "success": true,
  "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"
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "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",
      "createdAt": "2024-01-16T14:20:00.000Z",
      "updatedAt": "2024-01-16T14:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "total": 25,
    "count": 2
  }
}

Success Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful.
data	array	Array of metafield objects.
pagination	object	Contains pagination details (page, total, count).

Metafield Object Fields

Field	Type	Description
id	string	Unique identifier for the metafield.
fieldType	string	The entity type this metafield applies to.
label	string	Display label for the metafield.
description	string	Optional description of the metafield's purpose.
code	string	Unique code identifier (combined 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 (for select types).
displayFilter	boolean	Whether this field can be used as a filter.
predefinedValues	array	Array of predefined values (if hasPredefinedValues is true).
valueType	string	Data type of the metafield value.
createdAt	string	ISO 8601 timestamp of when the metafield was created.
updatedAt	string	ISO 8601 timestamp of when the metafield was last updated.

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

Error Response

• Status Code: 400 Bad Request

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

Notes

• The code and fieldType combination must be unique for each metafield.
• Maximum limit per page is 50. Values exceeding this will be capped.
• Pagination starts at page 1.