Custom Field Definitions

API version: unstable

These endpoints manage custom field definitions — the schema for a field (name, type, allowed values). To read or write field values on entity instances, see Custom Field Values.

Supported entities: products, products/variants, customers

Namespace format: must match ^[a-z][a-z0-9_-]*$ — lowercase alphanumeric, underscores, and hyphens; must start with a letter.

Restricted namespaces: custom, default, tiendanube, nuvemshop, system, admin, legacy — rejected with 422.

Beta access only

This feature is currently only available to stores enrolled in the beta program. If you are interested in participating, please contact us.

Common response

All definition endpoints return this shape (single object or array):

{
  "id": "color",
  "namespace": "myapp",
  "slug": "color",
  "key": "color",
  "name": "Color",
  "description": "The product color",
  "value_type": "text",
  "owner_resource": "products",
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-10T08:00:00Z"
}

Field	Type	Description
id	string	Same as slug
namespace	string	The app namespace
slug	string	The field slug
key	string	The field slug
name	string	Human-readable field name
description	string	Field description
value_type	string	Field type — see supported types below
owner_resource	string	Entity type (products, product_variants, customers)
created_at	ISO 8601	When the definition was created
updated_at	ISO 8601	When the definition was last updated

Supported value_type values

Type	Description
text	Free-form string
text_list	Constrained list of allowed string values
numeric	Numeric value
date	ISO 8601 date string
color	Color value
boolean	Boolean value
media	Media asset
ref	Reference to a single custom object entry
ref[]	Reference to multiple custom object entries
object	Inline structured object defined by a schema
object[]	Array of inline structured objects defined by a schema

Extra response fields by value_type

text_list

Field	Type	Description
values	array of strings	The allowed values for this field

ref and ref[]

Field	Type	Description
ref_type	string	Target custom object type in namespace/slug format

object and object[]

Field	Type	Description
schema	object	Schema describing the structure of the value — see Custom Object Schema DSL

---

Endpoints

POST /{entity}/custom-fields/{namespace}

Creates a new custom field definition.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Request body

{
  "slug": "color",
  "name": "Color",
  "description": "The product color",
  "value_type": "text"
}

Field	Type	Required	Description
slug	string	Yes	URL-safe identifier for the field
name	string	Yes	Human-readable field name
description	string	No	Field description
value_type	string	Yes	One of the supported types
capabilities	array	No	Capabilities to enable on creation — see Available capabilities

Extra request fields by value_type

text_list

Field	Type	Required	Description
values	array of strings	Yes	Allowed values for this field

{ "slug": "size", "name": "Size", "value_type": "text_list", "values": ["S", "M", "L", "XL"] }

ref and ref[]

Field	Type	Required	Description
ref_type	string	Yes	Target custom object type in namespace/slug format

{ "slug": "badge", "name": "Badge", "value_type": "ref", "ref_type": "myapp/badge" }

object and object[]

Field	Type	Required	Description
schema	object	Yes	Schema describing the structure of the value — see Custom Object Schema DSL

{
  "slug": "dimensions",
  "name": "Dimensions",
  "value_type": "object",
  "schema": {
    "kind": "object",
    "label": "Dimensions",
    "properties": {
      "width": { "kind": "number", "label": "Width" },
      "height": { "kind": "number", "label": "Height" }
    }
  }
}

Response

201 Created — single definition object

---

GET /{entity}/custom-fields

Returns all custom field definitions across all namespaces.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Response

200 OK — array of definition objects

---

GET /{entity}/custom-fields/{namespace}

Returns all custom field definitions for a specific namespace.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Response

200 OK — array of definition objects

---

GET /{entity}/custom-fields/{namespace}/{slug}

Returns a single custom field definition by namespace and slug.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Response

200 OK — single definition object

404 Not Found — definition not found

---

DELETE /{entity}/custom-fields/{namespace}/{slug}

Deletes a custom field definition and all values associated with it.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Response

204 No Content — definition deleted

404 Not Found — definition not found

---

Capabilities

Capabilities are optional behaviors that can be enabled on a definition. Each capability is identified by a name and accepts an optional arguments object.

They can be set at creation time (see capabilities in the create request body) or managed individually via the endpoints below.

Available capabilities

ADMIN_EDITABLE

Makes the field visible and editable on the entity form in the admin UI.

Argument	Type	Required	Description
group	string	No	Form group to place the field in
sort_order	integer	No	Sort order within the group

{ "capability": "ADMIN_EDITABLE", "arguments": { "group": "extra", "sort_order": 1 } }

---

STOREFRONT_FILTER

Makes the field available as a filter on the storefront. No arguments.

{ "capability": "STOREFRONT_FILTER" }

---

PUBLIC_READ

Makes the definition and its values readable by any actor. Without this capability, only the app that created the field can read it.

No arguments.

{ "capability": "PUBLIC_READ" }

---

PUBLIC_WRITE

Allows any actor to write values to the field. Without this capability, only the app that created the field can write values.

No arguments.

{ "capability": "PUBLIC_WRITE" }

---

COMPLETE_DURING_CHECKOUT

Requires the field to be completed during checkout. Only valid for customers fields.

Argument	Type	Required	Description
required	boolean	No	Whether the field must be filled in to complete checkout

{ "capability": "COMPLETE_DURING_CHECKOUT", "arguments": { "required": true } }

---

GET /{entity}/custom-fields/{namespace}/{slug}/capabilities

Returns the capabilities currently enabled on a definition.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Response

200 OK — array of capability objects

[
  { "capability": "PUBLIC_READ", "arguments": {} },
  { "capability": "ADMIN_EDITABLE", "arguments": { "group": "extra", "sort_order": 1 } }
]

---

POST /{entity}/custom-fields/{namespace}/{slug}/capabilities

Enables one or more capabilities on a definition.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Request body

{
  "capabilities": [
    { "capability": "PUBLIC_READ" },
    { "capability": "ADMIN_EDITABLE", "arguments": { "group": "extra" } }
  ]
}

Response

200 OK — updated definition object

---

DELETE /{entity}/custom-fields/{namespace}/{slug}/capabilities/{capability}

Removes a specific capability from a definition.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Response

204 No Content — capability removed

404 Not Found — definition or capability not found