> ## 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

> Create a new metafield definition. Admin API only.

# Create Metafield Definition

<Warning>
  Admin API only — requires a merchant JWT. Not exposed to OAuth apps.
</Warning>

Creates the schema (type + validations + label) for a metafield. Once a
definition exists, all writes to `(ownerType, namespace, key)` are
validated against it.

## Request

```bash theme={null}
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 (owner, or staff with admin/manager access).

## Body parameters

<ParamField body="namespace" type="string" required>
  Namespace (e.g. `custom`, your app handle, or anything else).
</ParamField>

<ParamField body="key" type="string" required>
  Machine name. Unique per `(storeId, ownerType, namespace)`.
</ParamField>

<ParamField body="name" type="string" required>
  Human label shown in the admin UI.
</ParamField>

<ParamField body="type" type="string" required>
  One of the 22 [supported types](/api-reference/metafields/overview#supported-types-22).
</ParamField>

<ParamField body="ownerType" type="string" required>
  One of the 9 [owner types](/api-reference/metafields/overview#owner-types-nine).
</ParamField>

<ParamField body="description" type="string">
  Tooltip / helper text shown in admin.
</ParamField>

<ParamField body="validations" type="object">
  Type-dependent validation rules. See
  [validation rules per type](/api-reference/metafields/definitions/overview#validation-rules-per-type).
</ParamField>

<ParamField body="pinned" type="boolean" default="false">
  If true, the field appears on the resource detail page in admin without
  the merchant having to click "Add custom data".
</ParamField>

## Examples

### Number with bounds

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

## Response

```json theme={null}
{
  "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

| Code               | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `UNAUTHORIZED`     | Invalid or missing JWT                                              |
| `FORBIDDEN`        | Wrong store / insufficient role                                     |
| `VALIDATION_ERROR` | Invalid type, owner type, or validation key                         |
| `DUPLICATE_KEY`    | A definition with this `(ownerType, namespace, key)` already exists |