Custom Data Engine

Extend Cartly's data model with typed MetafieldDefinitions and custom content types (Metaobjects) without writing code.

Metafield Definitions

MetafieldDefinitions declare a typed schema for metafields on a specific owner type (product, collection, order, customer). When a definition exists, the Service.Set() call validates the value against it before storing.

Owner Types

product, collection, order, customer, shop

Field Types (16 supported)

single_line_text, multi_line_text, number_integer, number_decimal, boolean, date, date_time, color, url, json, file_reference, metaobject_reference, product_reference, collection_reference, list.single_line_text, list.product_reference

POST/admin/metafield-definitionsadmin-jwt

Create a metafield definition. Once created, all writes to this namespace+key on the owner type are validated against it.

Request Body

json

{
  "field_type": "single_line_text",
  "key": "material",
  "name": "Material",
  "namespace": "custom",
  "owner_type": "product",
  "validations": {
    "max_length": 100
  }
}

Metaobjects

Metaobjects are custom structured content types — think CMS records with a typed schema. A MetaobjectDefinition declares the type (e.g., designer) and its FieldDefinitions. MetaobjectEntries are individual records of that type.

Use Cases

Designer profiles linked to products via metaobject_reference metafield
Size guides with structured columns
FAQ entries, team members, testimonials

GraphQL Access

Products and Collections expose metafield resolvers in the Storefront GraphQL API:

query {
  product(slug: "classic-tee") {
    metafield(namespace: "custom", key: "material") {
      value
      type
    }
    metafields(namespace: "custom", first: 10) {
      key
      value
    }
  }
}

Metaobject entries are queryable via:

query {
  metaobjects(type: "designer", limit: 10) {
    handle
    fields { key value type }
  }
  metaobject(type: "designer", handle: "alice-chen") {
    id
    fields { key value }
  }
}

Liquid Access

In theme templates, metafields are accessible on product and collection objects:

{{ product.metafields.custom.material }}
{{ product.metafields['custom']['material'] }}

Metaobjects are injected into the Liquid context when the section's schema declares a metaobjects dependency:

{% for entry in metaobjects.designer.entries %}
  <div>{{ entry.fields.name }}</div>
{% endfor %}

The metafield_tag Liquid filter generates a hidden <meta> tag for SEO structured data.