Create a metafield definition
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/metafield-definitions';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"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}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://apibase.ecomweb.app/api/v1/stores/example/metafield-definitions \ --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 }'Defines a metafield for one owner type: product, variant, collection, customer, order, page, blog_post, location or shop. owner_type, key, name and type are required; namespace defaults to custom. Types are the base types 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 and mixed_reference, or list. followed by a base type for a list of values. The validations object accepts only the keys that apply to the type, and list types also accept list_min and list_max. Namespace, key and type cannot change later. An owner type holds at most 100 definitions and 20 pinned ones; a duplicate namespace and key answers 409.
Required scopes: write:metafields
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The kind of resource the metafield attaches to. Required on create; cannot change afterwards.
Groups related metafields: 2 to 64 lowercase letters, digits or underscores. Defaults to custom; cannot change afterwards.
The key within the namespace: 2 to 64 lowercase letters, digits or underscores. Required on create; cannot change afterwards.
Human-readable name, 1 to 255 characters. Required on create.
What the metafield holds, up to 5000 characters.
The value type: a base type, or list. followed by a base type. Required on create; cannot change afterwards.
The rules values must meet. Which keys apply depends on the type; keys that do not apply are rejected.
object
Minimum text length, in characters. Text types.
Maximum text length, in characters. Text types and rich text.
A regular expression the text must match. Single-line text only, in a restricted dialect (no back-references or lookaround, at most 200 characters).
The only values allowed. Single-line text only, at most 128 choices.
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.
object
The amount, as a decimal string.
The unit. Weights use g, kg, oz or lb; volumes ml, cl, l, m3, fl_oz, pt, qt or gal; dimensions mm, cm, m, in, ft or yd.
Maximum number of decimal places. Decimal only.
Host names a link may point to. Url and link types, at most 20.
Lowest rating on the scale, as a decimal string. Rating only.
Highest rating on the scale, as a decimal string. Rating only.
The kinds of file allowed. File type only.
ID of the metaobject definition an entry reference must belong to. Metaobject reference only.
IDs of the metaobject definitions a mixed reference may point to, between 2 and 10.
Minimum number of items. List types only.
Maximum number of items, at most 128. List types only.
Whether the storefront API exposes the values. Defaults to false; not available for customer, order and location metafields.
None, read or read_write. Defaults to none. Customer metafields allow all three, order metafields none and read, every other owner type none.
Whether to pin the definition so it is listed first. At most 20 pinned definitions per owner type.
Responses
Section titled “Responses”object
Definition ID, as a string.
The kind of resource the metafield attaches to.
What the metafield holds.
The value type: a base type such as single_line_text, or list. followed by a base type for a list of values.
The rules values must meet. Empty when the definition sets none.
object
Minimum text length, in characters. Text types.
Maximum text length, in characters. Text types and rich text.
A regular expression the text must match. Single-line text only, in a restricted dialect (no back-references or lookaround, at most 200 characters).
The only values allowed. Single-line text only, at most 128 choices.
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.
object
The amount, as a decimal string.
The unit. Weights use g, kg, oz or lb; volumes ml, cl, l, m3, fl_oz, pt, qt or gal; dimensions mm, cm, m, in, ft or yd.
Maximum number of decimal places. Decimal only.
Host names a link may point to. Url and link types, at most 20.
Lowest rating on the scale, as a decimal string. Rating only.
Highest rating on the scale, as a decimal string. Rating only.
The kinds of file allowed. File type only.
ID of the metaobject definition an entry reference must belong to. Metaobject reference only.
IDs of the metaobject definitions a mixed reference may point to, between 2 and 10.
Minimum number of items. List types only.
Maximum number of items, at most 128. List types only.
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.
Position among the pinned definitions of its owner type, starting at 0, or null when the definition is not pinned.
ID of the user who created the definition, or null when it was created with an API key or the user has left.
When the definition was created, as an ISO 8601 timestamp.
When the definition was last updated, as an ISO 8601 timestamp.
Groups related metafields. Lowercase letters, digits and underscores; defaults to custom.
The metafield’s key within its namespace. Lowercase letters, digits and underscores.
Human-readable name.
Whether the storefront API exposes the values. Never available for customer, order and location metafields.
The definition’s namespace and key joined as namespace.key. Values are addressed by it.
Example
{ "owner_type": "product", "type": "single_line_text", "validations": { "file_types": [ "image" ] }, "customer_access": "none"}The request is malformed or failed validation.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The request conflicts with the resource’s current state.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}