Metafield definition guide

Metafield definitions specify the data structure, data type, and access permissions of metafields. Before writing metafield values, it is recommended that you create metafield definitions so that you can display and manage metafield definitions in the SHOPLINE Admin. This article explains how to manage metafield definitions through the REST Admin API.

What is a metafield definition​

A metafield definition is not a metafield value. The relationship between metafield definitions and metafield values is as follows:

A metafield definition includes the following core fields:

Use cases​

Create a metafield definition in the following scenarios:

• Extension fields that require long-term maintenance and have relatively fixed data types and data validation rules, such as product care instructions and compliance labels.

• Extension fields that must be displayed in and maintained by merchants in the SHOPLINE Admin.

• Metafields that require restricted access and management, such as metafields that only the app that created the metafield definition can access and manage.

Manage metafield definitions​

You can use the REST Admin API to create, get, update, and delete metafield definitions.

Prerequisites​

Before calling the REST Admin API, make sure that you meet the following requirements:

• You have created an app and completed store authorization.

• You have obtained a valid access token according to App authorization.

• You have identified the resource type to which the metafield definition belongs, such as products or orders, and the supported data type.

Access permissions​

When creating or updating a metafield definition, you can configure access permissions through access.admin. The access scope of each permission value is as follows:

Configure data validation rules​

When creating or updating a metafield definition, you can use validations to configure data validation rules based on the data type. Data validation rules restrict the values that can be written to metafields and prevent invalid or incorrect data. validations contains the following fields:

For complete rule names, supported data types, rule value formats, and validation behavior, refer to Data validation rules.

Create a metafield definition​

Endpoint: POST /metafield_definition.json

Create a metafield definition for a specified resource (owner_resource). For API details, refer to Create a metafield definition. Use the latest stable version.

Request example​

curl --request POST 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "definition": {
      "owner_resource": "products",
      "namespace": "size_fields",
      "key": "size_label",
      "name": "Size label",
      "description": "Product size label",
      "type": "single_line_text_field",
      "validations": [
        {
          "name": "choices",
          "value": "[\"S\",\"M\",\"L\",\"XL\"]"
        }
      ]
    }
  }'

Response example​

It is recommended that you save id, key, and namespace from the response for subsequent queries, updates, and metafield value writes.

{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Product size label",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-04-15T16:21:03+08:00"
  }
}

Get a metafield definition​

Endpoint: GET /metafield_definition.json

Get metafield definition details by metafield definition ID. For API details, refer to Get a metafield definition. Use the latest stable version.

Request example​

curl --request GET 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json?id={definition_id}' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}'

Response example​

{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Product size label",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-04-15T16:21:03+08:00"
  }
}

Update a metafield definition​

Endpoint: PUT /metafield_definition.json

Update the name, description, access permissions, and other information of an existing metafield definition. If an optional field is omitted or set to null, its original value is retained. An empty string clears the data. For API details, refer to Update a metafield definition. Use the latest stable version.

Request example​

curl --request PUT 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "definition": {
      "owner_resource": "products",
      "namespace": "size_fields",
      "key": "size_label",
      "name": "Size label",
      "description": "Updated description"
    }
  }'

Response example​

{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Updated description",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-07-15T16:54:00+08:00"
  }
}

Delete a metafield definition​

Endpoint: DELETE /metafield_definition.json

Delete a specified metafield definition. For API details, refer to Delete a metafield definition. Use the latest stable version.

FAQs​

When must you create a metafield definition first?​

You should create a metafield definition when you need to configure data validation rules for metafield values, display and manage fields in the SHOPLINE Admin, or set access permissions. If you only need to write metafield values quickly and can accept the management limitations of undefined metafields, consider using the Operate metafields in bulk API to write metafield values directly.

When should you configure data validation rules?​

Configure data validation rules through validations when creating or updating a metafield definition. You do not need to pass data validation rules again when writing metafield values. The value is automatically validated against the associated metafield definition.