Skip to main content
Version: 3.x

Metadata

Saleor gives you the possibility to customize your shop without modifying the core. You can extend most of the common models using the metadata API.

Metadata allows you to store additional information about each object, for example, external identifiers for items synchronized with a third-party platform. You can also use metadata to customize how your storefront looks and behaves.

Supported object types

The following models contain metadata fields in which data can be modified:

Private and public metadata

All objects support two sets of metadata:

  • metadata is public and visible to the unauthenticated users.
  • privateMetadata is protected and visible only to the staff users, plugins, and Apps with appropriate permissions.

Modifying both requires the permission to manage the item that metadata is attached to.

Querying metadata

All of the objects types listed above implement the same interface:

interface ObjectWithMetadata {
privateMetadata: [MetadataItem]!
metadata: [MetadataItem]!
}

Each metadata item is a key-value pair:

type MetadataItem {
key: String!
value: String!
}

Here's an example query that fetches the metadata of the first product:

{
products(first: 1) {
edges {
node {
id
name
metadata {
key
value
}
}
}
}
}

Response:

{
"data": {
"products": {
"edges": [
{
"node": {
"id": "UHJvZHVjdDo3Mg==",
"name": "Apple Juice",
"metadata": [
{
"key": "tax.group",
"value": "Food products"
}
]
}
}
]
}
}
}

Updating metadata

The following GraphQL mutations allow you to update and remove metadata:

type Mutation {
updateMetadata(id: ID!, input: [MetadataInput!]!): UpdateMetadata
updatePrivateMetadata(
id: ID!
input: [MetadataInput!]!
): UpdatePrivateMetadata
deleteMetadata(id: ID!, keys: [String!]!): DeleteMetadata
deletePrivateMetadata(id: ID!, keys: [String!]!): DeletePrivateMetadata
}
note

For Order and Checkout types, it is recommended to use token as the id input value; for other types, use GraphQL ID.

Changing the Order metadata is possible only with the use of token.

All resulting types have the same shape:

type UpdateMetadata {
metadataErrors: [MetadataError!]!
item: ObjectWithMetadata
}

Examples

Here's an example of how a product's metadata could be updated:

mutation {
updateMetadata(
id: "UHJvZHVjdDo3Mg=="
input: [{ key: "special_product", value: "true" }]
) {
metadataErrors {
field
code
}
item {
metadata {
key
value
}
}
}
}

And the same field being removed:

mutation {
deleteMetadata(id: "UHJvZHVjdDo3Mg==", keys: ["special_product"]) {
metadataErrors {
field
code
}
item {
metadata {
key
value
}
}
}
}

Filtering by metadata

Objects with metadata interface can be filtered by their values. Filtering is only available for public metadata.

query FavoriteProducts {
products(
filter: { metadata: { key: "isFavorite", value: "true" } }
first: 10
channel: "default-channel"
) {
edges {
node {
id
name
}
}
}
}

Response:

{
"data": {
"products": {
"edges": [
{
"node": {
"id": "UHJvZHVjdDoxNDA=",
"name": "Super Shirt"
}
}
]
}
}
}