Custom Objects

API version: unstable

Custom objects let you define your own structured data types (object definitions) and create instances of them (entries). They are primarily used as reference targets for ref and ref[] custom field types.

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.

Object Definitions

An object definition declares the schema for a custom object type — its name, slug, and a JSON Schema-like schema describing its properties.

Common response

{
  "namespace": "myapp",
  "slug": "badge",
  "name": "Badge",
  "description": "A product badge",
  "currentVersion": 1,
  "schemaVersion": 1,
  "schema": {
    "kind": "object",
    "label": "Badge",
    "required": ["label"],
    "properties": {
      "label": { "kind": "string", "label": "Label" }
    }
  },
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-10T08:00:00Z"
}

Field	Type	Description
namespace	string	The app namespace
slug	string	URL-safe identifier for this object type
name	string	Human-readable name
description	string	Description
currentVersion	integer	Current version of the definition
schemaVersion	integer	Schema version
schema	object	Schema describing the structure of entries — see Custom Object Schema DSL
created_at	ISO 8601	When the definition was created
updated_at	ISO 8601	When the definition was last updated

---

POST /custom-objects/{namespace}

Creates a new custom object definition.

Request body

{
  "slug": "badge",
  "name": "Badge",
  "description": "A product badge",
  "schema": {
    "kind": "object",
    "label": "Badge",
    "required": ["label"],
    "properties": {
      "label": { "kind": "string", "label": "Label" }
    }
  }
}

Field	Type	Required	Description
slug	string	Yes	URL-safe identifier for this object type
name	string	Yes	Human-readable name
description	string	No	Description
schema	object	Yes	Schema describing the structure of entries — see Custom Object Schema DSL

Response

201 Created — definition object

---

GET /custom-objects

Returns all custom object definitions across all namespaces.

Response

200 OK — array of definition objects

---

GET /custom-objects/{namespace}

Returns all custom object definitions for a specific namespace.

Response

200 OK — array of definition objects

---

GET /custom-objects/{namespace}/{slug}

Returns a single custom object definition.

Response

200 OK — definition object

404 Not Found — definition not found

---

PUT /custom-objects/{namespace}/{slug}

Updates an existing custom object definition.

Request body

{
  "name": "Updated Badge",
  "description": "An updated badge description",
  "schema": {
    "kind": "object",
    "label": "Badge",
    "required": ["label"],
    "properties": {
      "label": { "kind": "string", "label": "Label" }
    }
  }
}

Response

200 OK — updated definition object

404 Not Found — definition not found

---

DELETE /custom-objects/{namespace}/{slug}

Deletes a custom object definition and all its entries.

Response

204 No Content — definition deleted

404 Not Found — definition not found

---

Object Entries

Entries are instances of a custom object definition. Each entry has a slug identifier and a value object that must conform to the definition's schema.

Common response

{
  "namespace": "myapp",
  "definitionSlug": "badge",
  "definitionVersion": 1,
  "slug": "sale",
  "name": "Sale",
  "value": {
    "label": "Sale"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Field	Type	Description
namespace	string	The app namespace
definitionSlug	string	Slug of the object definition this entry belongs to
definitionVersion	integer	Version of the definition at creation time
slug	string	URL-safe identifier for this entry
name	string	Human-readable name
value	object	Entry data, conforming to the definition's schema
created_at	ISO 8601	When the entry was created
updated_at	ISO 8601	When the entry was last updated

---

POST /custom-objects/{namespace}/{typeSlug}/entries

Creates a new entry for a custom object type.

Request body

{
  "slug": "sale",
  "name": "Sale",
  "value": {
    "label": "Sale"
  }
}

Field	Type	Required	Description
slug	string	Yes	URL-safe identifier for this entry
name	string	Yes	Human-readable name
value	object	Yes	Entry data — must conform to the definition's schema

Response

201 Created — entry object

404 Not Found — definition not found

422 Unprocessable Entity — value does not conform to the definition's schema

---

GET /custom-objects/{namespace}/{typeSlug}/entries

Returns all entries for a custom object type.

Response

200 OK — array of entry objects

---

GET /custom-objects/{namespace}/{typeSlug}/entries/{entrySlug}

Returns a single entry.

Response

200 OK — entry object

404 Not Found — entry not found

---

PUT /custom-objects/{namespace}/{typeSlug}/entries/{entrySlug}

Updates an existing entry.

Request body

{
  "name": "Big Sale",
  "value": {
    "label": "Big Sale"
  }
}

Response

200 OK — updated entry object

404 Not Found — entry not found

422 Unprocessable Entity — value does not conform to the definition's schema

---

DELETE /custom-objects/{namespace}/{typeSlug}/entries/{entrySlug}

Deletes an entry.

Response

204 No Content — entry deleted

404 Not Found — entry not found