Standard Fields

API version: unstable

Standard fields are pre-defined field definitions provided by the platform. Unlike app-defined custom fields, their slug, schema, and meaning are fixed — apps and merchants opt-in by enabling them on a given entity type rather than declaring them from scratch.

Once enabled, a standard field behaves like any other Custom Field Definition: values are read and written through the standard Custom Field Values endpoints under the reserved standard namespace.

Internal-only management

Enabling and disabling standard fields is currently performed internally by Tiendanube / Nuvemshop and is not exposed to apps or merchants. The endpoints listed below are placeholders describing the intended public surface — they are not yet callable.

Once a standard field has been enabled for a store, however, its values can be read and written by any app with the appropriate scope through the regular Custom Field Values endpoints, using standard as the namespace (e.g. PUT /products/{id}/custom-fields/standard/rating_value/value).

What is a standard field?

A standard field is a canonical, platform-defined field that:

• Lives in the reserved standard namespace (which is otherwise blocked from normal create/delete operations).
• Has a fixed slug, schema, default display name, and default description maintained by the platform.
• Is opt-in: a tenant must explicitly enable it for a given entity type before values can be stored.
• Can be enabled with optional capabilities, subject to per-field restrictions (some standard fields block specific capabilities).
• Can be disabled, but only if no values have been stored against it.

Standard fields exist so that common, well-known attributes (a customer's date of birth, a product's average rating, etc.) are represented consistently across stores and apps — instead of every app inventing its own slug for the same concept.

Reading and writing values

Once a standard field is enabled for a store, it behaves like any other custom field. Use the Custom Field Values endpoints with standard as the namespace:

• GET /{entity}/{id}/custom-fields/standard — list all standard-namespace values on an entity instance
• PUT /{entity}/{id}/custom-fields/standard/{slug}/value — set a value
• DELETE /{entity}/{id}/custom-fields/standard/{slug}/value — clear a value
• PUT /{entity}/{id}/custom-fields/values — bulk set, using keys like standard/rating_value

The same scopes apply (read_products / write_products, read_customers / write_customers, etc.). No special permission is needed beyond what the host entity already requires.

Catalog

The current standard field catalog:

Slug	Entity	Type	Description	Notes
date_of_birth	customers	date	The customer's date of birth
gender	customers	string (enum)	The customer's gender	Allowed values: male, female, prefer-not-to-say, other
mkt_tags	customers	ref[] → standard/mkt_customer_tag	Tags assigned to this customer	COMPLETE_DURING_CHECKOUT capability is not allowed
rating_count	products	integer (min 0)	Total number of reviews submitted for this product
rating_value	products	number (0–5, 2 decimals)	Average rating score for this product

Common response

A catalog entry returned by the listing endpoint:

{
  "slug": "date_of_birth",
  "name": "Date of Birth",
  "description": "The customer's date of birth",
  "value_type": "date",
  "owner_resources": ["customer"],
  "schema": {
    "kind": "date",
    "label": "Date of Birth"
  },
  "enabled": false
}

Field	Type	Description
slug	string	Catalog slug (unique within the standard namespace)
name	string	Default human-readable name
description	string	Default description
value_type	string	Resolved value type (e.g. text, enum, date, integer, decimal, ref)
owner_resources	array of strings	Entity types this field can be enabled on
schema	object	Schema describing the value — see Custom Object Schema DSL
enabled	boolean	Whether the field is currently enabled for the requesting store

---

Endpoints

GET /{entity}/standard-fields

Lists all standard field catalog entries available for the given entity type, annotated with whether each one is currently enabled for the store.

Entity	Required scope
products	read_products
products/variants	read_products
customers	read_customers

Response

200 OK — array of catalog entry objects.

---

POST /{entity}/standard-fields/enable

Bulk-enables one or more standard fields for the entity type. Idempotent — already-enabled fields are returned as-is.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Request body

[
  {
    "namespace": "standard",
    "slug": "date_of_birth"
  },
  {
    "namespace": "standard",
    "slug": "gender",
    "capabilities": [
      { "capability": "ADMIN_EDITABLE", "arguments": { "group": "personal" } }
    ]
  }
]

Field	Type	Required	Description
namespace	string	Yes	Must be standard
slug	string	Yes	A slug from the catalog
capabilities	array	No	Capabilities to enable on creation — see Available capabilities

Response

201 Created — array of created field definition objects.

422 Unprocessable Entity — slug not in catalog, entity type not allowed for the slug, or capability blocked for the field.

---

POST /{entity}/standard-fields/enable/{namespace}/{slug}

Enables a single standard field. Idempotent — re-enabling returns the existing definition.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Request body

Optional list of capabilities to enable on creation:

[
  { "capability": "ADMIN_EDITABLE", "arguments": { "group": "personal" } }
]

Response

201 Created — field definition object.

422 Unprocessable Entity — slug not in catalog, entity type not allowed for the slug, or capability blocked for the field.

---

POST /{entity}/standard-fields/disable/{namespace}/{slug}

Disables (deletes) a previously-enabled standard field. Fails if any values have been stored against it.

Entity	Required scope
products	write_products
products/variants	write_products
customers	write_customers

Response

204 No Content — field disabled.

404 Not Found — field is not currently enabled.

409 Conflict — values exist for this field; delete them before disabling.