Custom Field Values

API version: unstable

These endpoints manage the stored values of custom fields on entity instances. To define custom fields, use the Custom Field Definitions API (stable).

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 value endpoints return this shape (single object or array):

{
  "namespace": "myapp",
  "owner_resource": "products",
  "value_type": "string",
  "key": "myapp/color",
  "name": "Color",
  "description": "The product color",
  "value": "red",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Field	Type	Description
namespace	string	The app namespace
owner_resource	string	Entity type (products, product_variants, customers)
value_type	string	Field type as defined in the definition
key	string	Composite key in namespace/slug format
name	string	Human-readable field name
description	string	Field description
value	any	The stored value (type depends on value_type)
created_at	ISO 8601	When the value was first set
updated_at	ISO 8601	When the value was last updated

Fields with null values are omitted from the response.

Endpoints

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

Returns all custom field values across all namespaces for a given entity instance.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Query parameters

Parameter	Type	Description
expand	string	Pass refs to expand reference-type field values inline

Response

200 OK — array of field value objects

---

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

Returns all custom field values scoped to a specific namespace for a given entity instance.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Query parameters

Parameter	Type	Description
expand	string	Pass refs to expand reference-type field values inline

Response

200 OK — array of field value objects

---

PUT /{entity}/{id}/custom-fields/{namespace}/{slug}/value

Creates or replaces the value of a specific field on an entity instance. The value is validated against the field definition's schema.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Request body

{
  "value": "red"
}

Field	Type	Required	Description
value	any	Yes	The value to set. Type must match the field definition's value_type.

Response

200 OK — single field value object

404 Not Found — definition not found

---

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

Removes the stored value of a field on an entity instance.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Response

204 No Content — value deleted

404 Not Found — definition or value not found

---

PUT /{entity}/{id}/custom-fields/values

Sets multiple field values at once for a given entity instance. Each entry identifies the definition by its namespace/slug key. The operation is transactional — if any definition is not found, the entire request rolls back.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Request body

{
  "values": [
    { "key": "myapp/color", "value": "red" },
    { "key": "myapp/size", "value": "XL" }
  ]
}

Field	Type	Required	Description
values	array	Yes	Must not be empty
values[].key	string	Yes	Definition key in namespace/slug format
values[].value	any	Yes	The value to set

Response

200 OK — array of field value objects, one per entry

400 Bad Request — validation errors or definition not found (rolls back all)

---

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

Returns the field definition and a paginated list of all entity instances that have a value set for it.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Query parameters

Parameter	Type	Default	Description
after	string	—	Cursor from a previous response's next_cursor for pagination
limit	integer	50	Number of owners to return. Clamped to [1, 200].

Response

200 OK

{
  "namespace": "myapp",
  "slug": "color",
  "key": "myapp/color",
  "name": "Color",
  "description": "The product color",
  "value_type": "string",
  "owner_resource": "products",
  "values": [],
  "ref_type": null,
  "schema": null,
  "capabilities": [],
  "owners": [
    { "entity_id": "123", "value": "red" },
    { "entity_id": "456", "value": "blue" }
  ],
  "next_cursor": "MTIz",
  "has_more": true,
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-10T08:00:00Z"
}

Field	Type	Description
namespace	string	The app namespace
slug	string	The field slug
key	string	Composite key in namespace/slug format
name	string	Human-readable field name
description	string	Field description
value_type	string	Field type
owner_resource	string	Entity type
values	array	Allowed values list (for text_list type)
ref_type	string	Reference type (for ref type)
schema	object	JSON schema for validation
capabilities	array	Enabled capabilities (e.g. filterable)
owners	array	Paginated list of { entity_id, value } pairs
next_cursor	string	Opaque cursor for the next page. Absent when has_more is false.
has_more	boolean	Whether more owners exist beyond this page
created_at	ISO 8601	Definition creation time
updated_at	ISO 8601	Definition last update time

404 Not Found — definition not found