Skip to content

Create a metaobject definition

POST
/stores/{storeRef}/metaobject-definitions
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/metaobject-definitions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "type": "example", "name": "example", "description": "example", "fields": [ { "key": "example", "name": "example", "description": "example", "type": "single_line_text", "required": true, "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 } } ], "display_name_key": "example", "filter_keys": [ "example" ], "has_status": true, "storefront_access": true, "customer_access": "none" }'

Defines a custom content type. name and fields are required; type is derived from the name when left out, and each field’s key is derived from its name. A definition holds at most 40 fields, up to 5 of them filter keys, and a store holds at most 100 definitions. The type handle cannot change later, and a type that already exists answers 409. Field types and validations follow the same rules as metafield definitions.

Required scopes: write:metaobjects

storeRef
required
string

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

Media typeapplication/json
object
type

The type handle, 2 to 64 lowercase letters, digits, underscores or hyphens. Derived from the name on create when left out; cannot change afterwards.

string
name

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

string
description

What the metaobject represents, up to 5000 characters.

string
nullable
fields

The fields entries can hold, at most 40. On update the list replaces the stored one: send every field to keep. A field in use as the display name or a filter cannot be removed.

Array<object>
object
key

The field’s key. 2 to 64 lowercase letters, digits or underscores. Derived from the name when left out.

string
name
required

Human-readable name, 1 to 255 characters.

string
description

What the field holds, up to 5000 characters.

string
nullable
type
required

The value type: a base type, or list. followed by a base type.

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
required

Whether every entry must have a value. Defaults to false.

boolean
validations

The rules values must meet.

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
display_name_key

Key of the field whose text names each entry.

string
nullable
filter_keys

Keys of the fields entries can be filtered by, at most 5. Only single_line_text, boolean, integer and date fields qualify; list types never do.

Array<string>
has_status

Whether entries have an active or draft status. Defaults to false.

boolean
storefront_access

Whether the storefront API exposes the entries. Defaults to false.

boolean
customer_access

None or read: whether a signed-in customer may read the entries. Defaults to none.

string
Allowed values: none read
Media typeapplication/json
object
id
required

Definition ID, as a string.

string
description
required

What the metaobject represents.

string
nullable
fields
required

The fields entries can hold.

Array<object>
object
description
required

What the field holds.

string
nullable
type
required

The value type, as for a metafield definition.

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.

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
key
required

The field’s key within entries. Lowercase letters, digits and underscores.

string
name
required

Human-readable name.

string
required
required

Whether every entry must have a value for the field.

boolean
display_name_key
required

Key of the field whose text names each entry, or null to name entries by handle.

string
nullable
filter_keys
required

Keys of the fields entries can be filtered by, at most 5.

Array<string>
customer_access
required

Whether a signed-in customer may read the entries: none or read.

string
Allowed values: none read
created_by
required

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

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
created_by_name

Name of the user who created the definition. Only present in the list; null when unknown.

string
nullable
type
required

The type handle. Entries are addressed by it in URLs. Lowercase letters, digits, underscores and hyphens.

string
name
required

Human-readable name.

string
has_status
required

Whether entries have an active or draft status. Without it every entry is active.

boolean
storefront_access
required

Whether the storefront API exposes the entries.

boolean
entry_count
required

Number of entries of this type.

number

Example

{
"fields": [
{
"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 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"
}