Skip to content

Get a metaobject definition

GET
/stores/{storeRef}/metaobject-definitions/{id}
curl --request GET \
--url https://apibase.ecomweb.app/api/v1/stores/example/metaobject-definitions/example \
--header 'x-api-key: <x-api-key>'

Returns one metaobject definition with its fields and its entry_count. The ID is the numeric definition ID, not the type handle.

Required scopes: read:metaobjects

id
required
string

The metaobject definition ID.

storeRef
required
string

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

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 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"
}