Skip to main content
POST
Create Metafield Definition

Create Metafield Definition

Admin API only — requires a merchant JWT. Not exposed to OAuth apps.
Creates the schema (type + validations + label) for a metafield. Once a definition exists, all writes to (ownerType, namespace, key) are validated against it.

Request

Auth

Merchant JWT (owner, or staff with admin/manager access).

Body parameters

namespace
string
required
Namespace (e.g. custom, your app handle, or anything else).
key
string
required
Machine name. Unique per (storeId, ownerType, namespace).
name
string
required
Human label shown in the admin UI.
type
string
required
One of the 22 supported types.
ownerType
string
required
One of the 9 owner types.
description
string
Tooltip / helper text shown in admin.
validations
object
Type-dependent validation rules. See validation rules per type.
pinned
boolean
default:"false"
If true, the field appears on the resource detail page in admin without the merchant having to click “Add custom data”.

Examples

Number with bounds

Single-line text with regex

List of references

URL with restricted schemes

Response

Error codes

CodeDescription
UNAUTHORIZEDInvalid or missing JWT
FORBIDDENWrong store / insufficient role
VALIDATION_ERRORInvalid type, owner type, or validation key
DUPLICATE_KEYA definition with this (ownerType, namespace, key) already exists