Create or Upsert Metafield
Metafields
Create or Upsert Metafield
Create a new metafield, or update if one already exists for the same owner+namespace+key
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. Use your app handle (e.g.
subscriptions_pro) — custom is
the merchant-managed namespace.Field key. Unique per
(ownerType, namespace, ownerId).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.The value. Scalars are sent as-is (string, number, boolean). Compound
types (
weight, dimension, volume, money, rating, lists, JSON)
are sent as JSON.One of
shop, product, variant, collection, customer, order,
page, blog, article. Lowercase only.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 underdata.metafield.
201 if created, 200 if updated.success or error.Human-readable message, or
null on success.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
| Status | Description |
|---|---|
400 | A required field is missing (namespace, key, value, ownerType, ownerId) |
401 | Invalid or missing access token |
403 | App doesn’t have the write_metafields scope |
500 | Unexpected server error while upserting |