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_type | The record | Written on | Read on |
|---|---|---|---|
product | A product | Dashboard, Merchant API (POST /products, PUT /products/{product}, PATCH /products/{product}/metafields) | Public API (/store/products), Merchant API, products/* webhooks |
variant | One variant of a product | Dashboard (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 |
collection | One of the store's own collections | Dashboard, Merchant API (PUT /collections/{collection}) | Public API (/store/collections), Merchant API |
post | A blog post (not a page, gallery or policy) | Dashboard, Merchant API (POST /posts, PUT /posts/{post}) | Public API (/store/posts), Merchant API |
order | An order | Merchant API (POST /orders, PATCH /orders/{order}), dashboard | Merchant API, orders/* webhooks, and the customer's own orders when marked customer_visible |
customer | One of the store's customers | Dashboard (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:
| Metafields | Metadata | |
|---|---|---|
| What | Typed, 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 it | Themes, site builders, AI store builders, filters. | Only the integrator that wrote it. Queek never interprets or renders it. |
| On records | All six types above. | Products and orders only. |
| On the public API | Yes, when the merchant switches the field on — see access. | No. Metadata is private to the Merchant API and to webhooks. |
| Filterable | Products 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:
| Switch | Who it lets in | Default | Applies to |
|---|---|---|---|
storefront_visible | Anyone 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_visible | The signed-in customer, on their own account and orders: read-only. | Off | customer 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:
| Type | Value shape | Also as a list |
|---|---|---|
single_line_text | string | list.single_line_text |
multi_line_text | string | list.multi_line_text |
integer | number | list.integer |
decimal | number | list.decimal |
boolean | true / false | list.boolean |
date | YYYY-MM-DD string | list.date |
url | string | list.url |
json | any JSON | — |
media_id | an image URL on read | list.media_id — an array of URLs |
metaobject_reference | A reference to an entry of the metaobject type named in validations.metaobject_type | list.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.
| Rule | Applies to | Meaning |
|---|---|---|
min, max | numbers | Inclusive bounds on the value. |
min, max | text | Bounds on the character length. |
min, max | date | Earliest / latest date, YYYY-MM-DD. |
min, max | list.* | Bounds on the list length. |
regex | text | A pattern the value must match. |
choices | scalars | The only values allowed. Render it as a select. |
metaobject_type | metaobject_reference | The 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.
| Limit | Value |
|---|---|
| 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 value | 65,536 |
| Metadata keys per resource (products and orders) | 50 |
| Metadata key length | 64 characters |
| Metadata value length | 500 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.
{
"metafields": [
{ "namespace": "custom", "key": "fabric", "value": "cotton" },
{ "namespace": "custom", "key": "warranty_months", "value": 24 },
{ "namespace": "custom", "key": "old_note", "value": null }
]
}"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": nullclears 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 answers422 metafield_definition_missing; a value that fails its type orvalidationsanswers422naming 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: abooleanis a JSON boolean, anintegera number, alist.*a JSON array. Amedia_idfield 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:
- Inside the product save. Put
metafieldson a variant ofPOST /productsorPUT /products/{product}:variants: [{ "id": "…", "metafields": [ … ], … }]. A save replaces the product's variants, so send every existing variant'sidback (the Merchant API returns it asuid). A variant sent without anidis a new variant and starts blank; a variant left out of the save is deleted, andvariants: []deletes them all. - On a single variant.
POST /products/{product}/variantsandPATCH /products/{product}/variants/{variant}takemetafieldsbeside the variant's fields, and leave its siblings' values alone. - Values only.
PATCH /products/{product}/variants/{variant}/metafieldstakes onlymetafields, under themerchant-metafields-updatescope: an app that keeps a field per variant never needsmerchant-items-update. It answers the product, and sends oneproducts/updatelike 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:
| Resource | Where |
|---|---|
| Product | Every product from GET /store/products and GET /store/products/{slug} |
| Variant | Each entry of the product's variants[] |
| Collection | GET /store/collections and the collection embedded in GET /store/collections/{collection}/products |
| Blog post | GET /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:
| Field | Type | Notes |
|---|---|---|
p_id | integer | The definition's short id. |
handle | string | namespace.key — the key you will see on the record. |
owner_type | string | The type you asked for. |
namespace, key | string | The two halves of the handle. |
type | string | One of the types in the next section. |
name | string | Human label. Use it for the field's label. |
description | string | null | Help text. Use it for tooltips; never guess what a handle means. |
validations | object | The rules values must satisfy — see Validations. |
storefront_visible | boolean | Always true in this list: only visible definitions are listed. |
customer_visible | boolean | Whether the signed-in customer sees it on their account (customer and order fields only, so false here). |
pinned, pinned_position | boolean, integer | Whether the merchant pinned the field, and its position among pinned fields. Use them to order the fields you show. |
created_at, updated_at | ISO 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 toPATCH /auth/me) carriesmetafields—{}when the store marked none; - their own orders:
GET /store/ordersandGET /store/orders/{id}carrymetafieldson 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.
jsonand everylist.*type cannot be filtered; asking is ametafield_value_invalid. - The value is typed by the definition.
metafield[custom.warranty_months]=24compares as the integer 24;metafield[custom.on_sale]=1,yesandonall compare astrue. Text is compared as given. - Each value is at most 255 characters.
- Combine freely with
keyword,category_slug,sort,pageandper_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:
| Topics | Carry |
|---|---|
products/* | The product's metafields, and metafields on every variant in variants[] — including fields that are not storefront_visible. |
customers/create, customers/update | The 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.code | Status | When | Extra keys in error |
|---|---|---|---|
metafield_definition_missing | 422 | A write or a filter names a handle this store has not defined for that record type. | handle, owner_type, field |
metafield_value_invalid | 422 | A filter value the definition cannot hold, or a filter on a json / list.* field. | handle, owner_type, expected_type, field |
metafield_namespace_reserved | 422 | A 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.
Authentication
Headless API authentication — one header, public and secret keys, the allowed-websites rule and every failure code.
Payments
What happens between checkout_url and orders/paid, where the customer lands afterwards, the Idempotency-Key contract, and stores that collect through their own provider account.