Skip to main content
POST
/
metafield-definitions
Create Metafield Definition
curl --request POST \
  --url https://api.launchmystore.io/metafield-definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "namespace": "<string>",
  "key": "<string>",
  "name": "<string>",
  "type": "<string>",
  "ownerType": "<string>",
  "description": "<string>",
  "validations": {},
  "pinned": true
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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

curl -X POST "https://api.launchmystore.io/metafield-definitions" \
  -H "Authorization: Bearer <merchant-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "custom",
    "key": "warranty_years",
    "name": "Warranty (years)",
    "description": "How many years of warranty are included",
    "type": "number_integer",
    "ownerType": "product",
    "validations": { "min": 0, "max": 25 },
    "pinned": true
  }'

​
Auth

Merchant JWT (MERCHANT, STAFF_ADMIN, SUPER_ADMIN, MANAGER).

​
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

{
  "namespace": "custom",
  "key": "warranty_years",
  "name": "Warranty (years)",
  "type": "number_integer",
  "ownerType": "product",
  "validations": { "min": 0, "max": 25 },
  "pinned": true
}

​
Single-line text with regex

{
  "namespace": "custom",
  "key": "sku_internal",
  "name": "Internal SKU",
  "type": "single_line_text_field",
  "ownerType": "product",
  "validations": { "regex": "^[A-Z0-9-]{6,12}$" }
}

​
List of references

{
  "namespace": "custom",
  "key": "related_products",
  "name": "Related products",
  "type": "list.product_reference",
  "ownerType": "product",
  "validations": { "list_min": 0, "list_max": 10 }
}

​
URL with restricted schemes

{
  "namespace": "custom",
  "key": "demo_link",
  "name": "Demo link",
  "type": "url",
  "ownerType": "product",
  "validations": { "allowed_schemes": ["https"] }
}

​
Response

{
  "status": 201,
  "state": "success",
  "data": {
    "id": "f7e3a920-...",
    "namespace": "custom",
    "key": "warranty_years",
    "name": "Warranty (years)",
    "type": "number_integer",
    "owner_type": "product",
    "validations": { "min": 0, "max": 25 },
    "pinned": true,
    "app_id": null,
    "created_at": "2026-05-09T13:30:00.000Z",
    "updated_at": "2026-05-09T13:30:00.000Z"
  }
}

​
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