Skip to main content
POST
Create or Upsert Metafield

Create or Upsert Metafield

This endpoint upserts: if a metafield with the same (ownerType, namespace, key, ownerId) already exists for your app, the value is updated; otherwise a new metafield is created. There is always at most one metafield per (resource, namespace, key) per app.

Request

Required scope

write_metafields

Body parameters

namespace
string
required
Namespace. Use your app handle (e.g. subscriptions_pro) — custom is the merchant-managed namespace.
key
string
required
Field key. Unique per (ownerType, namespace, ownerId).
type
string
One of the supported types. Stored verbatim and used by the storefront when decoding/rendering the value. The App API does not validate value against the type — it is your app’s responsibility to send a well-formed value for the type you declare. If omitted, type defaults to single_line_text_field.
value
any
required
The value. Scalars are sent as-is (string, number, boolean). Compound types (weight, dimension, volume, money, rating, lists, JSON) are sent as JSON.
ownerType
string
required
One of shop, product, variant, collection, customer, order, page, blog, article. Lowercase only.
ownerId
string
required
The id of the owning resource. Required for every owner type except shop.

Examples by type

Scalar text

Number

Boolean

Rich text (HTML, rendered unescaped in Aqua)

Measurement

Money

Reference

List

JSON (free-form structured data)

Response

The response is the standard envelope. On success the created/updated metafield is returned under data.metafield.
status
integer
201 if created, 200 if updated.
state
string
success or error.
message
string
Human-readable message, or null on success.
data.metafield
object
The created or updated metafield row. value is returned as the stored string form (scalars stringified, compound types JSON-encoded). See List Metafields for shape.

Example response

This OAuth App API path performs no type validation — it stores the value as-is. Value validation against the declared type only runs on the merchant-managed metafields path, not here. A malformed value is accepted and stored; the only 400 returned is for missing required fields (namespace, key, value, ownerType, ownerId).

Cache invalidation

A successful upsert automatically expires the cached copy of the owning resource and any cached page HTML that rendered it. The next storefront render sees the new value.

Error codes

StatusDescription
400A required field is missing (namespace, key, value, ownerType, ownerId)
401Invalid or missing access token
403App doesn’t have the write_metafields scope
500Unexpected server error while upserting