Metadata definitions

GET `/metadata-definitions`

List the organization's metadata definitions: the typed fields its customers, products, variants and orders carry in metadata. Filter by resource to get one resource's fields in order.

Requires the settings:read permission.

Query parameters

limitnumber

The number of records to return.

cursorstring

A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

The sort order. Prefix a field with - to sort descending. Defaults to position.

filterstring

A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, resource, key, name, type, storefront, createdAt. See Filtering for the syntax.

Request

curl \
  "https://your-store.meisei.app/api/metadata-definitions" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getMetadataDefinitions } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getMetadataDefinitions()

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

page = meisei.metadata_definitions.list

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

page = meisei.metadata_definitions.list()

Response

{
  "data": [
    {
      "id": "A4Ws1igz",
      "resource": "customers",
      "key": "string",
      "name": "string",
      "description": "string",
      "type": "text",
      "options": ["..."],
      "rules": {
        "required": "...",
        "min": "...",
        "max": "...",
        "maxLength": "...",
        "pattern": "..."
      },
      "storefront": true,
      "position": 0,
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "nextCursor": "string"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the metadata definition.",
            "idCodec": "sqid"
          },
          "resource": {
            "type": "string",
            "enum": ["customers", "products", "productVariants", "orders"],
            "description": "Which records the definition applies to."
          },
          "key": {
            "type": "string",
            "description": "The key in the records' `metadata` object this definition types."
          },
          "name": {
            "type": "string",
            "description": "The field's label, used in the dashboard and in validation messages."
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Help text for the field, if it has any."
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "number",
              "integer",
              "boolean",
              "date",
              "dateTime",
              "url",
              "select",
              "multiSelect"
            ],
            "description": "What the key holds. `text` and `url` are strings, `number` and `integer` are numbers, `boolean` is true or false, `date` is `YYYY-MM-DD`, `dateTime` is an ISO 8601 timestamp, `select` is one option's value and `multiSelect` is a list of option values."
          },
          "options": {
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100,
                  "description": "What is stored when the option is picked."
                },
                "label": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100,
                  "description": "What the dashboard shows for the option."
                }
              },
              "required": ["value", "label"],
              "additionalProperties": false
            },
            "description": "The choices a `select` or `multiSelect` field offers. Empty for every other type."
          },
          "rules": {
            "type": "object",
            "properties": {
              "required": {
                "description": "When true, a record has to carry the key. Checked when a record is created and whenever a write touches the key, so adding a required field does not invalidate records that predate it.",
                "type": "boolean"
              },
              "min": {
                "description": "For `number` and `integer`, the smallest value allowed.",
                "type": "number"
              },
              "max": {
                "description": "For `number` and `integer`, the largest value allowed.",
                "type": "number"
              },
              "maxLength": {
                "description": "For `text` and `url`, the most characters a value can have.",
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "pattern": {
                "description": "For `text`, a regular expression every value has to match. A pattern that repeats a group with a repeat inside it, such as `(a+)+`, is refused.",
                "type": "string",
                "maxLength": 500
              }
            },
            "additionalProperties": false,
            "description": "Optional rules a value is checked against. Which ones apply depends on the type."
          },
          "storefront": {
            "type": "boolean",
            "description": "Whether storefront widgets may read this key. Off by default, since metadata is otherwise private to your organization."
          },
          "position": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Where the field sits among its resource's fields, lowest first."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the definition was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the definition was last changed."
          }
        },
        "required": [
          "id",
          "resource",
          "key",
          "name",
          "description",
          "type",
          "options",
          "rules",
          "storefront",
          "position",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "description": "The page of records, in the requested sort order."
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass this back as `cursor` to fetch the next page. Null once the last page has been returned."
    }
  },
  "required": ["data", "nextCursor"],
  "additionalProperties": false
}

POST `/metadata-definitions`

Define a metadata field. From then on every write of that key on the resource is checked against its type and rules. Values already stored that convert, such as the text "12" for a number, are rewritten in the background; the rest are left as they are.

Requires the settings:write permission.

Body parameters

resourcecustomers | products | productVariants | ordersrequired

Which records the definition applies to.

keystringrequired

The key in metadata to type. Starts with a letter, then letters, digits and underscores, up to 64 characters. It cannot be changed later.

namestringrequired

The field's label.

descriptionstring | null

Optional help text for the field.

What the key holds. text and url are strings, number and integer are numbers, boolean is true or false, date is YYYY-MM-DD, dateTime is an ISO 8601 timestamp, select is one option's value and multiSelect is a list of option values.

optionsobject[]

The choices a select or multiSelect field offers. Empty for every other type.

rulesobject

Optional rules a value is checked against. Which ones apply depends on the type.

storefrontboolean

Whether storefront widgets may read this key. Defaults to false.

positioninteger

Where the field sits among its resource's fields. Defaults to after the last one.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/metadata-definitions" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resource": "customers",
  "key": "string",
  "name": "string",
  "description": "string",
  "type": "text",
  "options": [
    {
      "value": "string",
      "label": "string"
    }
  ],
  "rules": {
    "required": true,
    "min": 0,
    "max": 0,
    "maxLength": 0,
    "pattern": "string"
  },
  "storefront": true,
  "position": 0
}'

Request

import { client } from "@meisei/api/admin/client"
import { postMetadataDefinitions } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postMetadataDefinitions({
  body: {
    resource: "customers",
    key: "string",
    name: "string",
    description: "string",
    type: "text",
    options: [
      {
        value: "string",
        label: "string",
      },
    ],
    rules: {
      required: true,
      min: 0,
      max: 0,
      maxLength: 0,
      pattern: "string",
    },
    storefront: true,
    position: 0,
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.create(
  resource: "customers",
  key: "string",
  name: "string",
  description: "string",
  type: "text",
  options: [{ value: "string", label: "string" }],
  rules: { required: true, min: 0, max: 0, max_length: 0, pattern: "string" },
  storefront: true,
  position: 0,
)

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.create(
    resource="customers",
    key="string",
    name="string",
    description="string",
    type="text",
    options=[{"value": "string", "label": "string"}],
    rules={"required": True, "min": 0, "max": 0, "max_length": 0, "pattern": "string"},
    storefront=True,
    position=0,
)

Response

{
  "id": "A4Ws1igz",
  "resource": "customers",
  "key": "string",
  "name": "string",
  "description": "string",
  "type": "text",
  "options": [
    {
      "value": "string",
      "label": "string"
    }
  ],
  "rules": {
    "required": true,
    "min": 0,
    "max": 0,
    "maxLength": 0,
    "pattern": "string"
  },
  "storefront": true,
  "position": 0,
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the metadata definition.",
      "idCodec": "sqid"
    },
    "resource": {
      "type": "string",
      "enum": ["customers", "products", "productVariants", "orders"],
      "description": "Which records the definition applies to."
    },
    "key": {
      "type": "string",
      "description": "The key in the records' `metadata` object this definition types."
    },
    "name": {
      "type": "string",
      "description": "The field's label, used in the dashboard and in validation messages."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Help text for the field, if it has any."
    },
    "type": {
      "type": "string",
      "enum": [
        "text",
        "number",
        "integer",
        "boolean",
        "date",
        "dateTime",
        "url",
        "select",
        "multiSelect"
      ],
      "description": "What the key holds. `text` and `url` are strings, `number` and `integer` are numbers, `boolean` is true or false, `date` is `YYYY-MM-DD`, `dateTime` is an ISO 8601 timestamp, `select` is one option's value and `multiSelect` is a list of option values."
    },
    "options": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What is stored when the option is picked."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What the dashboard shows for the option."
          }
        },
        "required": ["value", "label"],
        "additionalProperties": false
      },
      "description": "The choices a `select` or `multiSelect` field offers. Empty for every other type."
    },
    "rules": {
      "type": "object",
      "properties": {
        "required": {
          "description": "When true, a record has to carry the key. Checked when a record is created and whenever a write touches the key, so adding a required field does not invalidate records that predate it.",
          "type": "boolean"
        },
        "min": {
          "description": "For `number` and `integer`, the smallest value allowed.",
          "type": "number"
        },
        "max": {
          "description": "For `number` and `integer`, the largest value allowed.",
          "type": "number"
        },
        "maxLength": {
          "description": "For `text` and `url`, the most characters a value can have.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "pattern": {
          "description": "For `text`, a regular expression every value has to match. A pattern that repeats a group with a repeat inside it, such as `(a+)+`, is refused.",
          "type": "string",
          "maxLength": 500
        }
      },
      "additionalProperties": false,
      "description": "Optional rules a value is checked against. Which ones apply depends on the type."
    },
    "storefront": {
      "type": "boolean",
      "description": "Whether storefront widgets may read this key. Off by default, since metadata is otherwise private to your organization."
    },
    "position": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Where the field sits among its resource's fields, lowest first."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was last changed."
    }
  },
  "required": [
    "id",
    "resource",
    "key",
    "name",
    "description",
    "type",
    "options",
    "rules",
    "storefront",
    "position",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The new metadata definition."
}

GET `/metadata-definitions/{id}`

Get a single metadata definition by ID, with a count of the stored values it would refuse.

Requires the settings:read permission.

Path parameters

idstringrequired

The ID of the metadata definition.

Request

curl \
  "https://your-store.meisei.app/api/metadata-definitions/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getMetadataDefinitionsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getMetadataDefinitionsById({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.retrieve("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.retrieve("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "resource": "customers",
  "key": "string",
  "name": "string",
  "description": "string",
  "type": "text",
  "options": [
    {
      "value": "string",
      "label": "string"
    }
  ],
  "rules": {
    "required": true,
    "min": 0,
    "max": 0,
    "maxLength": 0,
    "pattern": "string"
  },
  "storefront": true,
  "position": 0,
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "nonConformingCount": 0
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the metadata definition.",
      "idCodec": "sqid"
    },
    "resource": {
      "type": "string",
      "enum": ["customers", "products", "productVariants", "orders"],
      "description": "Which records the definition applies to."
    },
    "key": {
      "type": "string",
      "description": "The key in the records' `metadata` object this definition types."
    },
    "name": {
      "type": "string",
      "description": "The field's label, used in the dashboard and in validation messages."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Help text for the field, if it has any."
    },
    "type": {
      "type": "string",
      "enum": [
        "text",
        "number",
        "integer",
        "boolean",
        "date",
        "dateTime",
        "url",
        "select",
        "multiSelect"
      ],
      "description": "What the key holds. `text` and `url` are strings, `number` and `integer` are numbers, `boolean` is true or false, `date` is `YYYY-MM-DD`, `dateTime` is an ISO 8601 timestamp, `select` is one option's value and `multiSelect` is a list of option values."
    },
    "options": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What is stored when the option is picked."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What the dashboard shows for the option."
          }
        },
        "required": ["value", "label"],
        "additionalProperties": false
      },
      "description": "The choices a `select` or `multiSelect` field offers. Empty for every other type."
    },
    "rules": {
      "type": "object",
      "properties": {
        "required": {
          "description": "When true, a record has to carry the key. Checked when a record is created and whenever a write touches the key, so adding a required field does not invalidate records that predate it.",
          "type": "boolean"
        },
        "min": {
          "description": "For `number` and `integer`, the smallest value allowed.",
          "type": "number"
        },
        "max": {
          "description": "For `number` and `integer`, the largest value allowed.",
          "type": "number"
        },
        "maxLength": {
          "description": "For `text` and `url`, the most characters a value can have.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "pattern": {
          "description": "For `text`, a regular expression every value has to match. A pattern that repeats a group with a repeat inside it, such as `(a+)+`, is refused.",
          "type": "string",
          "maxLength": 500
        }
      },
      "additionalProperties": false,
      "description": "Optional rules a value is checked against. Which ones apply depends on the type."
    },
    "storefront": {
      "type": "boolean",
      "description": "Whether storefront widgets may read this key. Off by default, since metadata is otherwise private to your organization."
    },
    "position": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Where the field sits among its resource's fields, lowest first."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was last changed."
    },
    "nonConformingCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many records hold a value for this key that the field would refuse, such as text in a number field. They were stored before the field was defined or retyped, and are checked again the next time each record is saved."
    }
  },
  "required": [
    "id",
    "resource",
    "key",
    "name",
    "description",
    "type",
    "options",
    "rules",
    "storefront",
    "position",
    "createdAt",
    "updatedAt",
    "nonConformingCount"
  ],
  "additionalProperties": false,
  "description": "The requested metadata definition."
}

PATCH `/metadata-definitions/{id}`

Change a metadata field's label, type, options, rules or position. Its resource and key cannot be changed.

Requires the settings:write permission.

Path parameters

idstringrequired

The ID of the metadata definition to update.

Body parameters

namestring

The field's label.

descriptionstring | null

Help text for the field. Null removes it.

A new type for the field. Stored values that convert, such as the text "12" for a number, are rewritten in the background; the rest are left as they are and are checked the next time each record is saved.

optionsobject[]

Replaces the field's options wholesale.

rulesobject

Replaces the field's rules wholesale.

storefrontboolean

Whether storefront widgets may read this key.

positioninteger

Where the field sits among its resource's fields.

Request

curl \
  -X PATCH \
  "https://your-store.meisei.app/api/metadata-definitions/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "type": "text",
  "options": [
    {
      "value": "string",
      "label": "string"
    }
  ],
  "rules": {
    "required": true,
    "min": 0,
    "max": 0,
    "maxLength": 0,
    "pattern": "string"
  },
  "storefront": true,
  "position": 0
}'

Request

import { client } from "@meisei/api/admin/client"
import { patchMetadataDefinitionsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await patchMetadataDefinitionsById({
  path: { id: "A4Ws1igz" },
  body: {
    name: "string",
    description: "string",
    type: "text",
    options: [
      {
        value: "string",
        label: "string",
      },
    ],
    rules: {
      required: true,
      min: 0,
      max: 0,
      maxLength: 0,
      pattern: "string",
    },
    storefront: true,
    position: 0,
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.update(
  "A4Ws1igz",
  name: "string",
  description: "string",
  type: "text",
  options: [{ value: "string", label: "string" }],
  rules: { required: true, min: 0, max: 0, max_length: 0, pattern: "string" },
  storefront: true,
  position: 0,
)

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.update(
    "A4Ws1igz",
    name="string",
    description="string",
    type="text",
    options=[{"value": "string", "label": "string"}],
    rules={"required": True, "min": 0, "max": 0, "max_length": 0, "pattern": "string"},
    storefront=True,
    position=0,
)

Response

{
  "id": "A4Ws1igz",
  "resource": "customers",
  "key": "string",
  "name": "string",
  "description": "string",
  "type": "text",
  "options": [
    {
      "value": "string",
      "label": "string"
    }
  ],
  "rules": {
    "required": true,
    "min": 0,
    "max": 0,
    "maxLength": 0,
    "pattern": "string"
  },
  "storefront": true,
  "position": 0,
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the metadata definition.",
      "idCodec": "sqid"
    },
    "resource": {
      "type": "string",
      "enum": ["customers", "products", "productVariants", "orders"],
      "description": "Which records the definition applies to."
    },
    "key": {
      "type": "string",
      "description": "The key in the records' `metadata` object this definition types."
    },
    "name": {
      "type": "string",
      "description": "The field's label, used in the dashboard and in validation messages."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Help text for the field, if it has any."
    },
    "type": {
      "type": "string",
      "enum": [
        "text",
        "number",
        "integer",
        "boolean",
        "date",
        "dateTime",
        "url",
        "select",
        "multiSelect"
      ],
      "description": "What the key holds. `text` and `url` are strings, `number` and `integer` are numbers, `boolean` is true or false, `date` is `YYYY-MM-DD`, `dateTime` is an ISO 8601 timestamp, `select` is one option's value and `multiSelect` is a list of option values."
    },
    "options": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What is stored when the option is picked."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What the dashboard shows for the option."
          }
        },
        "required": ["value", "label"],
        "additionalProperties": false
      },
      "description": "The choices a `select` or `multiSelect` field offers. Empty for every other type."
    },
    "rules": {
      "type": "object",
      "properties": {
        "required": {
          "description": "When true, a record has to carry the key. Checked when a record is created and whenever a write touches the key, so adding a required field does not invalidate records that predate it.",
          "type": "boolean"
        },
        "min": {
          "description": "For `number` and `integer`, the smallest value allowed.",
          "type": "number"
        },
        "max": {
          "description": "For `number` and `integer`, the largest value allowed.",
          "type": "number"
        },
        "maxLength": {
          "description": "For `text` and `url`, the most characters a value can have.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "pattern": {
          "description": "For `text`, a regular expression every value has to match. A pattern that repeats a group with a repeat inside it, such as `(a+)+`, is refused.",
          "type": "string",
          "maxLength": 500
        }
      },
      "additionalProperties": false,
      "description": "Optional rules a value is checked against. Which ones apply depends on the type."
    },
    "storefront": {
      "type": "boolean",
      "description": "Whether storefront widgets may read this key. Off by default, since metadata is otherwise private to your organization."
    },
    "position": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Where the field sits among its resource's fields, lowest first."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was last changed."
    }
  },
  "required": [
    "id",
    "resource",
    "key",
    "name",
    "description",
    "type",
    "options",
    "rules",
    "storefront",
    "position",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The updated metadata definition."
}

DELETE `/metadata-definitions/{id}`

Delete a metadata definition. The values records already carry stay, as free-form metadata.

Requires the settings:write permission.

Path parameters

idstringrequired

The ID of the metadata definition to delete.

Request

curl \
  -X DELETE \
  "https://your-store.meisei.app/api/metadata-definitions/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { deleteMetadataDefinitionsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteMetadataDefinitionsById({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.delete("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.metadata_definitions.delete("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "resource": "customers",
  "key": "string",
  "name": "string",
  "description": "string",
  "type": "text",
  "options": [
    {
      "value": "string",
      "label": "string"
    }
  ],
  "rules": {
    "required": true,
    "min": 0,
    "max": 0,
    "maxLength": 0,
    "pattern": "string"
  },
  "storefront": true,
  "position": 0,
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the metadata definition.",
      "idCodec": "sqid"
    },
    "resource": {
      "type": "string",
      "enum": ["customers", "products", "productVariants", "orders"],
      "description": "Which records the definition applies to."
    },
    "key": {
      "type": "string",
      "description": "The key in the records' `metadata` object this definition types."
    },
    "name": {
      "type": "string",
      "description": "The field's label, used in the dashboard and in validation messages."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Help text for the field, if it has any."
    },
    "type": {
      "type": "string",
      "enum": [
        "text",
        "number",
        "integer",
        "boolean",
        "date",
        "dateTime",
        "url",
        "select",
        "multiSelect"
      ],
      "description": "What the key holds. `text` and `url` are strings, `number` and `integer` are numbers, `boolean` is true or false, `date` is `YYYY-MM-DD`, `dateTime` is an ISO 8601 timestamp, `select` is one option's value and `multiSelect` is a list of option values."
    },
    "options": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What is stored when the option is picked."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "What the dashboard shows for the option."
          }
        },
        "required": ["value", "label"],
        "additionalProperties": false
      },
      "description": "The choices a `select` or `multiSelect` field offers. Empty for every other type."
    },
    "rules": {
      "type": "object",
      "properties": {
        "required": {
          "description": "When true, a record has to carry the key. Checked when a record is created and whenever a write touches the key, so adding a required field does not invalidate records that predate it.",
          "type": "boolean"
        },
        "min": {
          "description": "For `number` and `integer`, the smallest value allowed.",
          "type": "number"
        },
        "max": {
          "description": "For `number` and `integer`, the largest value allowed.",
          "type": "number"
        },
        "maxLength": {
          "description": "For `text` and `url`, the most characters a value can have.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "pattern": {
          "description": "For `text`, a regular expression every value has to match. A pattern that repeats a group with a repeat inside it, such as `(a+)+`, is refused.",
          "type": "string",
          "maxLength": 500
        }
      },
      "additionalProperties": false,
      "description": "Optional rules a value is checked against. Which ones apply depends on the type."
    },
    "storefront": {
      "type": "boolean",
      "description": "Whether storefront widgets may read this key. Off by default, since metadata is otherwise private to your organization."
    },
    "position": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Where the field sits among its resource's fields, lowest first."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the definition was last changed."
    }
  },
  "required": [
    "id",
    "resource",
    "key",
    "name",
    "description",
    "type",
    "options",
    "rules",
    "storefront",
    "position",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The deleted metadata definition."
}

#Metadata definitions

GET /metadata-definitions

Query parameters

POST /metadata-definitions

Body parameters

GET /metadata-definitions/{id}

Path parameters

PATCH /metadata-definitions/{id}

Path parameters

Body parameters

DELETE /metadata-definitions/{id}

Path parameters

Metadata definitions

GET `/metadata-definitions`

POST `/metadata-definitions`

GET `/metadata-definitions/{id}`

PATCH `/metadata-definitions/{id}`

DELETE `/metadata-definitions/{id}`