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.
Metafield Definitions
A definition is the schema for a metafield: it sets the type,
validation rules, human label, and whether the field is pinned to the
resource detail page in admin. Values that conflict with the definition’s
type or validations are rejected at write time.
Definition CRUD lives on the Admin API (merchant JWT) only. It is
not exposed to OAuth-scoped apps. Apps can write metafield values
without ever creating a definition — the type+validation contract is
optional. Definitions exist primarily to power the merchant Settings →
Custom data admin UI.
Why definitions exist
| Without a definition | With a definition |
|---|
| Apps can write any type to any namespace/key | Type is enforced at write time |
No human label — admin shows the raw key | Human-friendly name, description |
| Doesn’t appear in the admin “Custom data” picker | Listed in Settings → Custom data |
| Doesn’t auto-show on the resource edit page | If pinned: true, appears on the resource form |
| Validation rules can’t be enforced centrally | min, max, regex, choices, etc. all enforced |
Schema
| Field | Type | Notes |
|---|
id | UUID | server-generated |
storeId | UUID | scoped per store |
namespace | string | e.g. custom, my_app, specs |
key | string | machine name |
name | string | human label shown in admin |
type | enum | one of the 22 supported types |
owner_type | enum | one of the 9 owner types |
validations | object | type-dependent — min, max, regex, choices, list_min, list_max, allowed_schemes, etc. |
description | string | optional admin tooltip |
pinned | bool | if true, appears on the resource detail edit page |
created_at, updated_at | ISO timestamp | – |
(storeId, ownerType, namespace, key) — one
definition per (owner kind, namespace, key) per store.
Validation rules per type
The validations object’s allowed keys depend on type:
| Type | Allowed validations |
|---|
single_line_text_field | min, max, regex, choices |
multi_line_text_field | min, max, regex |
rich_text_field | – |
number_integer | min, max |
number_decimal | min, max, max_precision |
boolean | – |
color | – |
date, date_time | min, max (ISO strings) |
weight, dimension, volume | – |
money | – |
rating | – (constrained by scale_min / scale_max in the value itself) |
url | allowed_schemes (defaults to ["https","http","mailto","tel"]) |
json | – |
*_reference | – |
list.<innerType> | list_min, list_max + inner-type validations applied per item |
Endpoints
| Method | Route | Description |
|---|
GET | /metafield-definitions | List with filters |
POST | /metafield-definitions | Create |
GET | /metafield-definitions/:id | Get one |
PUT | /metafield-definitions/:id | Update |
DELETE | /metafield-definitions/:id | Delete |
Auth
Merchant JWT with one of: MERCHANT, STAFF_ADMIN, SUPER_ADMIN,
MANAGER. The storeId is resolved from the token (or parentId for
staff/manager).
Notes for app developers
- You can still write metafield values under your own namespace
without creating a definition first. The platform won’t enforce types
unless you’ve defined them.
- If you want merchants to see and edit your fields in the admin, ask the
merchant (or your install flow) to create matching definitions. The
definition + value combination is what populates the admin UI.
- Deleting a definition does not delete the values. Values persist;
they just lose the schema. Cleaning up values requires explicit
DELETE /metafields/:id calls.
