Skip to content

Set product metafields

PUT
/stores/{storeRef}/products/{id}/metafields
curl --request PUT \
--url https://apibase.ecomweb.app/api/v1/stores/example/products/example/metafields \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "values": [ { "namespace": "example", "key": "example", "value": {} } ] }'

Sets, updates or deletes metafield values on this product in one request. Each item names a definition by namespace and key, and a value of null deletes the stored value. Every value is checked against its definition’s type and validations before anything is saved, and one invalid item fails the whole request. Returns the same list as the GET.

Required scopes: write:products

id
required
string

The product ID.

storeRef
required
string

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

Media typeapplication/json
object
values

The values to set. Each is validated against its definition before anything is written, and one invalid value fails the whole request.

Array<object>
object
namespace
required

The definition’s namespace.

string
key
required

The definition’s key.

string
value
required

The new value, in the form the definition’s type defines. Send null to delete the stored value.

nullable
One of:
string

Example generated

{
"values": [
{
"namespace": "example",
"key": "example",
"value": {}
}
]
}
Media typeapplication/json
Array<object>
object
definition
required

The metafield’s definition.

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

The stored value, in the form its type defines, or null when the resource has no value for it.

nullable
One of:
string
references
required

For reference types, what each referenced ID points to, keyed by ID. Empty for other types.

object
key
additional properties
object
image_url
required

Its image, when it has one.

string
nullable
id
required

ID of the referenced record.

string
label
required

Its name or title. Falls back to the ID when the record is missing.

string
missing
required

True when the referenced record no longer exists.

boolean

Example

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