Queek docs

Custom fields (metafields)

The store's own typed fields on products, variants, collections, blog posts, orders and customers — definitions, the two access switches, how to write and read them, webhooks and limits.

A merchant can extend Queek's records with fields of their own — fabric, warranty months, a size-chart image, an ERP reference, a loyalty tier. In the dashboard they are called custom fields (Settings → Custom Fields); in the API they are metafields. Six kinds of record can carry them, and each field is defined once (custom.fabric is a single_line_text) before any value is written against the definition.

owner_typeThe recordWritten onRead on
productA productDashboard, Merchant API (POST /products, PUT /products/{product}, PATCH /products/{product}/metafields)Public API (/store/products), Merchant API, products/* webhooks
variantOne variant of a productDashboard (the variant's own drawer), Merchant API (inside the product save, the single-variant routes, or PATCH /products/{product}/variants/{variant}/metafields)Public API (each entry of a product's variants[]), Merchant API, products/* webhooks
collectionOne of the store's own collectionsDashboard, Merchant API (PUT /collections/{collection})Public API (/store/collections), Merchant API
postA blog post (not a page, gallery or policy)Dashboard, Merchant API (POST /posts, PUT /posts/{post})Public API (/store/posts), Merchant API
orderAn orderMerchant API (POST /orders, PATCH /orders/{order}), dashboardMerchant API, orders/* webhooks, and the customer's own orders when marked customer_visible
customerOne of the store's customersDashboard (the customer's profile)Merchant API, customers/* webhooks, and the customer's own auth/me when marked customer_visible

A customer's birthday is an ordinary customer field, not a custom field.

Metafields and metadata

Two primitives carry a merchant's own data, and they are deliberately different things:

MetafieldsMetadata
WhatTyped, defined fields. The merchant declares custom.fabric is single_line_text once; every value written after that is validated against the definition.Free-form string key/values an integrator writes for its own bookkeeping — an ERP id, a channel reference.
Who reads itThemes, site builders, AI store builders, filters.Only the integrator that wrote it. Queek never interprets or renders it.
On recordsAll six types above.Products and orders only.
On the public APIYes, when the merchant switches the field on — see access.No. Metadata is private to the Merchant API and to webhooks.
FilterableProducts only, exact match.Never.

{} on either means the store has defined or written none, or none that the reader may see.

Who can read a field

Access is a property of the definition, not of the value. Every definition carries two switches, and the merchant owns both:

SwitchWho it lets inDefaultApplies to
storefront_visibleAnyone using the public API: the field's values appear on the record and its definition in the schema list.On for product. Off for variant, collection and post: the merchant opts each field in.product, variant, collection, post. It has no effect on order or customer fields, which are never public.
customer_visibleThe signed-in customer, on their own account and orders: read-only.Offcustomer and order only. Turning it on for any other type is refused with 422.

The merchant, their Merchant API keys and their webhooks are not limited by either switch and see every field of a variant, collection, post, order or customer. The one exception is a product's own metafields on the Merchant API and in products/* webhooks, which lists the fields marked storefront_visible (the default for products). Both switches can be changed at any time, and a change applies at once.

Defining a field

In the dashboard, a merchant creates a definition in Settings → Custom Fields, choosing what it applies to, its type and, optionally, its validations and the two switches. An integration does the same with POST /metafield-definitions (scope merchant-metafields-create). The body carries owner_type, namespace, key, type, name and optionally description, validations, storefront_visible, customer_visible and pinned.

Once a definition exists its namespace, key, owner_type and type are immutable; only name, description, validations and the display and access flags change. A tightened validation applies to future writes only. Deleting a definition deletes every value written against it. Read the list with GET /metafield-definitions, optionally narrowed with ?owner_type=.

Over the Merchant API, changing and deleting a definition is open to an installed app for its own installation fields only (its settings and state, read and written with GET and PATCH /app/metafields): PATCH /metafield-definitions/{definition} and DELETE /metafield-definitions/{definition} answer 404 for every other definition. The merchant changes and deletes their own fields in the dashboard.

Types

Ten scalar types, and a list. form of every scalar except json:

TypeValue shapeAlso as a list
single_line_textstringlist.single_line_text
multi_line_textstringlist.multi_line_text
integernumberlist.integer
decimalnumberlist.decimal
booleantrue / falselist.boolean
dateYYYY-MM-DD stringlist.date
urlstringlist.url
jsonany JSON—
media_idan image URL on readlist.media_id — an array of URLs
metaobject_referenceA reference to an entry of the metaobject type named in validations.metaobject_typelist.metaobject_reference

Validations

validations is honoured per type. A rule the type cannot support is rejected when the definition is created, so a rule you read here always applies.

RuleApplies toMeaning
min, maxnumbersInclusive bounds on the value.
min, maxtextBounds on the character length.
min, maxdateEarliest / latest date, YYYY-MM-DD.
min, maxlist.*Bounds on the list length.
regextextA pattern the value must match.
choicesscalarsThe only values allowed. Render it as a select.
metaobject_typemetaobject_referenceThe metaobject type the reference must point to. Read entries with the metaobject operations.

Limits

These are part of the contract, so you can design around them. They are also machine-readable in the OpenAPI document under x-queek-metafields.

LimitValue
Definitions per store (all six owner types together)200
Metafield values per record (one product, variant, collection, post, order or customer)50
Bytes per serialised value65,536
Metadata keys per resource (products and orders)50
Metadata key length64 characters
Metadata value length500 characters

The two shapes: writing and reading

A value is written as a list of {namespace, key, value} and read as an object keyed namespace.key. The read shape is always an object, and {} when there is nothing to show.

Write
{
  "metafields": [
    { "namespace": "custom", "key": "fabric", "value": "cotton" },
    { "namespace": "custom", "key": "warranty_months", "value": 24 },
    { "namespace": "custom", "key": "old_note", "value": null }
  ]
}
Read
"metafields": {
  "custom.fabric": "cotton",
  "custom.warranty_months": 24
}

The rules for a write, the same on every record type:

  • It is a partial update. A key you leave out keeps its value, and "value": null clears one. Sending a few keys never wipes the rest.
  • Each entry must reference an existing definition of that record's owner_type. A handle that is not defined answers 422 metafield_definition_missing; a value that fails its type or validations answers 422 naming the field. A definition for a product never accepts a value on a collection, even with the same handle.
  • At most 50 entries per request, and 50 values stored per record.
  • Keys are handles, namespace.key, sorted on read. Values arrive in the definition's type: a boolean is a JSON boolean, an integer a number, a list.* a JSON array. A media_id field arrives already resolved to an image URL, never as an id.

Each record type

Products

Write metafields on POST /products and PUT /products/{product}. Read them on every product the public API, the Merchant API and products/* webhooks return. Filter by one on the public API (below).

Variants

A variant's values belong to that variant. Write them one of three ways:

  1. Inside the product save. Put metafields on a variant of POST /products or PUT /products/{product}: variants: [{ "id": "…", "metafields": [ … ], … }]. A save replaces the product's variants, so send every existing variant's id back (the Merchant API returns it as uid). A variant sent without an id is a new variant and starts blank; a variant left out of the save is deleted, and variants: [] deletes them all.
  2. On a single variant. POST /products/{product}/variants and PATCH /products/{product}/variants/{variant} take metafields beside the variant's fields, and leave its siblings' values alone.
  3. Values only. PATCH /products/{product}/variants/{variant}/metafields takes only metafields, under the merchant-metafields-update scope: an app that keeps a field per variant never needs merchant-items-update. It answers the product, and sends one products/update like any other value write.

A variant's values are deleted with the variant — when a save drops it, when it is deleted, or when its product is permanently deleted. Duplicating a product and importing a CSV do not carry variant values.

Collections

Only the store's own collections carry values; the shared product taxonomy never does. Send metafields with PUT /collections/{collection} (the call also takes the collection's name, which is required) and read the collection back with GET /collections/{collection} or the list. A bulk create (POST /collections/bulk) refuses metafields with a 422 instead of dropping them: create the collection, then set its fields.

Blog posts

Only blog posts carry values, never pages, galleries or policies: asking to write one on those is refused with 422, and they show no metafields key. Send metafields on POST /posts and PUT /posts/{post}. A value is live the moment it is saved, even while the post itself is still a draft, and autosaving a draft never touches values.

Orders

POST /orders and PATCH /orders/{order} take metafields. PATCH changes only these developer-extension fields and metadata, never the order's state. The namespaces queek and app belong to Queek and installed apps: a merchant key cannot write them. Order metafields are written only by the merchant side, never by a shopper: a value a visitor could set would be a forged record, not an extension point.

Customers

A customer's custom fields are written in the dashboard, on the customer's profile (creating or editing a customer). The Merchant API reads them on every customer in GET /customers, GET /customers/{customer} and the updated_after walk, with one rule: like a customer's name, email and phone, they read as {} unless the key holds the merchant-customers-contact-read scope.

Reading on the public API

Every public resource that can carry a field has a metafields object, {} when the store has none switched on:

ResourceWhere
ProductEvery product from GET /store/products and GET /store/products/{slug}
VariantEach entry of the product's variants[]
CollectionGET /store/collections and the collection embedded in GET /store/collections/{collection}/products
Blog postGET /store/posts, GET /store/posts/{slug} and its related[] (blog posts only; pages and galleries have no metafields)
"metafields": {
  "custom.fabric": "cotton",
  "custom.warranty_months": 24,
  "custom.size_chart": "https://cdn.usequeek.com/…/size-chart.jpg"
}

Only fields whose definition has storefront_visible on are returned, so a variant, collection or post field is absent until the merchant switches it on. Free-form metadata is never on these payloads.

Reading the schema

A handle alone tells you nothing about what it means, what type it holds or what values are legal. The store's public definitions are readable exactly because their values already are:

curl "https://client.usequeek.com/v1/store/metafield-definitions?owner_type=variant" \
  -H "X-Client-Key: pk_live_your_key_here" \
  -H "Accept: application/json"

owner_type is product (the default), variant, collection or post. A handle is only unique within one owner type, so each call lists one type; ask once per type you render. Any other value, including order and customer, is a 422. data is the list of definitions the merchant switched on (storefront_visible), ordered by namespace, key:

FieldTypeNotes
p_idintegerThe definition's short id.
handlestringnamespace.key — the key you will see on the record.
owner_typestringThe type you asked for.
namespace, keystringThe two halves of the handle.
typestringOne of the types in the next section.
namestringHuman label. Use it for the field's label.
descriptionstring | nullHelp text. Use it for tooltips; never guess what a handle means.
validationsobjectThe rules values must satisfy — see Validations.
storefront_visiblebooleanAlways true in this list: only visible definitions are listed.
customer_visiblebooleanWhether the signed-in customer sees it on their account (customer and order fields only, so false here).
pinned, pinned_positionboolean, integerWhether the merchant pinned the field, and its position among pinned fields. Use them to order the fields you show.
created_at, updated_atISO 8601

The response is not paginated: a store holds at most 200 definitions across every owner type.

Order and customer fields stay private

Order and customer definitions are a description of a merchant's back office — ERP ids, wholesale account codes — so no order or customer value is ever public and neither is its schema. A customer reads only the fields the merchant marked customer_visible, and only on their own account, as described next.

On the customer's own account

A signed-in customer sees only the fields the merchant marked customer_visible, on their own data, read-only:

  • their own customer record: GET /auth/me (and the reply to PATCH /auth/me) carries metafields — {} when the store marked none;
  • their own orders: GET /store/orders and GET /store/orders/{id} carry metafields on each order, never another customer's.

The customer cannot write a custom field, and none is returned to a request without their customer token.

Filtering products by a metafield

GET /store/products accepts metafield[handle]=value. The category, collection and promotion listings do not take it in v1 — filter the full catalogue and narrow with category_slug instead:

curl "https://client.usequeek.com/v1/store/products?metafield\[custom.fabric\]=cotton&metafield\[custom.fit\]=slim" \
  -H "X-Client-Key: pk_live_your_key_here"

The rules, all of them:

  • Exact match only. No ranges, no IN, no partial or case-insensitive match in v1.
  • Up to 5 handles per request, ANDed. A product must match every one.
  • Scalar types only. json and every list.* type cannot be filtered; asking is a metafield_value_invalid.
  • The value is typed by the definition. metafield[custom.warranty_months]=24 compares as the integer 24; metafield[custom.on_sale]=1, yes and on all compare as true. Text is compared as given.
  • Each value is at most 255 characters.
  • Combine freely with keyword, category_slug, sort, page and per_page.

An undefined handle is refused, not answered with an empty page — an empty list would be indistinguishable from "no product has that value":

{
  "status": "failed",
  "error_code": "metafield_definition_missing",
  "message": "No metafield definition 'custom.colour' exists for product. Create the definition on the Merchant API before sending a value.",
  "data": null,
  "error": {
    "code": "metafield_definition_missing",
    "message": "No metafield definition 'custom.colour' exists for product. …",
    "field": "metafield.custom.colour",
    "handle": "custom.colour",
    "owner_type": "product",
    "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#metafield_definition_missing",
    "request_id": "…"
  }
}

Webhooks

Webhooks carry custom field values so a receiver can match a record to its own without a second call:

TopicsCarry
products/*The product's metafields, and metafields on every variant in variants[] — including fields that are not storefront_visible.
customers/create, customers/updateThe customer's metafields.
orders/*The order's metafields and metadata.

Changing only a field's value still announces the record, though no ordinary column moved: products/update (once, whether a product's own or a variant's values changed), customers/update and orders/updated. Collections and blog posts have no webhook topics, so a change to their fields sends nothing.

Reserved namespaces

The namespace queek — and any namespace starting queek_ — is reserved for Queek's own first-party fields. A definition there is refused with metafield_namespace_reserved, and a first-party field can never collide with one you already ship. Use a namespace of your own; custom is the conventional one.

The namespace app — and any namespace starting app_ — is reserved for installed apps: an app creates its own definitions in exactly app_{its slug} (hyphens as underscores; a longer namespace such as app_{its slug}_dev is another app's) and owns them (only that app reads and writes their values through the API; see App capabilities). Anyone else is refused.

Error codes

error.codeStatusWhenExtra keys in error
metafield_definition_missing422A write or a filter names a handle this store has not defined for that record type.handle, owner_type, field
metafield_value_invalid422A filter value the definition cannot hold, or a filter on a json / list.* field.handle, owner_type, expected_type, field
metafield_namespace_reserved422A definition was requested in a reserved namespace.namespace

A value that fails its definition's type or validations on a write is a 422 that names the field, for example metafields.0.value. expected_type is the definition's type, so the repair — send a value of that type — is derivable from the response without parsing the message.

On this page