Skip to content

Update a metafield definition

PATCH
/stores/{storeRef}/metafield-definitions/{id}
curl --request PATCH \
--url https://apibase.ecomweb.app/api/v1/stores/example/metafield-definitions/example \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "owner_type": "product", "namespace": "example", "key": "example", "name": "example", "description": "example", "type": "single_line_text", "validations": { "min_length": 1, "max_length": 1, "regex": "example", "choices": [ "example" ], "min": { "value": "example", "unit": "example" }, "max": { "value": "example", "unit": "example" }, "max_precision": 1, "allowed_domains": [ "example" ], "scale_min": "example", "scale_max": "example", "file_types": [ "image" ], "metaobject_definition_id": "example", "metaobject_definition_ids": [ "example" ], "list_min": 1, "list_max": 1 }, "storefront_access": true, "customer_access": "none", "pinned": true }'

Changes a definition’s name, description, validations, storefront or customer access, or pinned state. Send only the properties to change; the merged definition is validated as a whole. Owner type, namespace, key and type cannot change and answer 400. Pinning is limited to 20 definitions per owner type.

Required scopes: write:metafields

id
required
string

The metafield definition ID.

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
owner_type

The kind of resource the metafield attaches to. Required on create; cannot change afterwards.

string
Allowed values: product variant collection customer order page blog_post location shop
namespace

Groups related metafields: 2 to 64 lowercase letters, digits or underscores. Defaults to custom; cannot change afterwards.

string
key

The key within the namespace: 2 to 64 lowercase letters, digits or underscores. Required on create; cannot change afterwards.

string
name

Human-readable name, 1 to 255 characters. Required on create.

string
description

What the metafield holds, up to 5000 characters.

string
nullable
type

The value type: a base type, or list. followed by a base type. Required on create; cannot change afterwards.

string
Allowed values: single_line_text multi_line_text rich_text email integer decimal date date_time url link weight volume dimension boolean color rating money language json file image video product variant collection page blog_post customer order metaobject_reference mixed_reference list.single_line_text list.multi_line_text list.rich_text list.email list.integer list.decimal list.date list.date_time list.url list.link list.weight list.volume list.dimension list.boolean list.color list.rating list.money list.language list.json list.file list.image list.video list.product list.variant list.collection list.page list.blog_post list.customer list.order list.metaobject_reference list.mixed_reference
validations

The rules values must meet. Which keys apply depends on the type; keys that do not apply are rejected.

object
min_length

Minimum text length, in characters. Text types.

integer
max_length

Maximum text length, in characters. Text types and rich text.

integer
regex

A regular expression the text must match. Single-line text only, in a restricted dialect (no back-references or lookaround, at most 200 characters).

string
choices

The only values allowed. Single-line text only, at most 128 choices.

Array<string>
min

Smallest allowed value: a number for integer, a decimal string for decimal, a date or date-time string, or a value with a unit for weight, volume and dimension.

One of:
number
max

Largest allowed value, in the same form as min.

One of:
number
max_precision

Maximum number of decimal places. Decimal only.

integer
allowed_domains

Host names a link may point to. Url and link types, at most 20.

Array<string>
scale_min

Lowest rating on the scale, as a decimal string. Rating only.

string
scale_max

Highest rating on the scale, as a decimal string. Rating only.

string
file_types

The kinds of file allowed. File type only.

Array<string>
Allowed values: image video document
metaobject_definition_id

ID of the metaobject definition an entry reference must belong to. Metaobject reference only.

string
metaobject_definition_ids

IDs of the metaobject definitions a mixed reference may point to, between 2 and 10.

Array<string>
list_min

Minimum number of items. List types only.

integer
list_max

Maximum number of items, at most 128. List types only.

integer
storefront_access

Whether the storefront API exposes the values. Defaults to false; not available for customer, order and location metafields.

boolean
customer_access

None, read or read_write. Defaults to none. Customer metafields allow all three, order metafields none and read, every other owner type none.

string
Allowed values: none read read_write
pinned

Whether to pin the definition so it is listed first. At most 20 pinned definitions per owner type.

boolean
Media typeapplication/json
object
id
required

Definition ID, as a string.

string
owner_type
required

The kind of resource the metafield attaches to.

string
Allowed values: product variant collection customer order page blog_post location shop
description
required

What the metafield holds.

string
nullable
type
required

The value type: a base type such as single_line_text, or list. followed by a base type for a list of values.

string
Allowed values: single_line_text multi_line_text rich_text email integer decimal date date_time url link weight volume dimension boolean color rating money language json file image video product variant collection page blog_post customer order metaobject_reference mixed_reference list.single_line_text list.multi_line_text list.rich_text list.email list.integer list.decimal list.date list.date_time list.url list.link list.weight list.volume list.dimension list.boolean list.color list.rating list.money list.language list.json list.file list.image list.video list.product list.variant list.collection list.page list.blog_post list.customer list.order list.metaobject_reference list.mixed_reference
validations
required

The rules values must meet. Empty when the definition sets none.

object
min_length

Minimum text length, in characters. Text types.

integer
max_length

Maximum text length, in characters. Text types and rich text.

integer
regex

A regular expression the text must match. Single-line text only, in a restricted dialect (no back-references or lookaround, at most 200 characters).

string
choices

The only values allowed. Single-line text only, at most 128 choices.

Array<string>
min

Smallest allowed value: a number for integer, a decimal string for decimal, a date or date-time string, or a value with a unit for weight, volume and dimension.

One of:
number
max

Largest allowed value, in the same form as min.

One of:
number
max_precision

Maximum number of decimal places. Decimal only.

integer
allowed_domains

Host names a link may point to. Url and link types, at most 20.

Array<string>
scale_min

Lowest rating on the scale, as a decimal string. Rating only.

string
scale_max

Highest rating on the scale, as a decimal string. Rating only.

string
file_types

The kinds of file allowed. File type only.

Array<string>
Allowed values: image video document
metaobject_definition_id

ID of the metaobject definition an entry reference must belong to. Metaobject reference only.

string
metaobject_definition_ids

IDs of the metaobject definitions a mixed reference may point to, between 2 and 10.

Array<string>
list_min

Minimum number of items. List types only.

integer
list_max

Maximum number of items, at most 128. List types only.

integer
customer_access
required

What a signed-in customer may do with the values: none, read, or read_write. Only customer metafields allow read_write, and customer and order metafields allow read.

string
Allowed values: none read read_write
pinned_position
required

Position among the pinned definitions of its owner type, starting at 0, or null when the definition is not pinned.

integer
nullable
created_by
required

ID of the user who created the definition, or null when it was created with an API key or the user has left.

string
nullable
created_at
required

When the definition was created, as an ISO 8601 timestamp.

string format: date-time
updated_at
required

When the definition was last updated, as an ISO 8601 timestamp.

string format: date-time
namespace
required

Groups related metafields. Lowercase letters, digits and underscores; defaults to custom.

string
key
required

The metafield’s key within its namespace. Lowercase letters, digits and underscores.

string
name
required

Human-readable name.

string
storefront_access
required

Whether the storefront API exposes the values. Never available for customer, order and location metafields.

boolean
identifier
required

The definition’s namespace and key joined as namespace.key. Values are addressed by it.

string

Example

{
"owner_type": "product",
"type": "single_line_text",
"validations": {
"file_types": [
"image"
]
},
"customer_access": "none"
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The resource does not exist in this store.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The request conflicts with the resource’s current state.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}