Collection data model

Updated:

A collection of items/products/services

View field support, webhooks, and list parameters for each integration on the Supported Integrations page.

Data Model
FieldTypeRequiredDescription
idstringNo
created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
namestringYesThe collection's name
public_namestringNo
descriptionstringNo
public_descriptionstringNo
mediaCommerceItemMedia[]No
media[].idstringNo
media[].urlstringYes
media[].altstringNo
media[].typeenumNoValues: image, video
media[].heightnumberNo
media[].widthnumberNo
media[].positionnumberNo1 is the first
media[].metadataCommerceMetadata[]No
media[].metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
media[].metadata[].valueobjectNoThe field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES_NO as true/false; MULTIPLE_SELECT as an array of option values; otherwise a string.
media[].metadata[].namespacestringNo
media[].metadata[].formatenumNoThe data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
media[].metadata[].extra_dataobjectNo
media[].metadata[].slugstringNoThe integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.
media[].metadata[].descriptionstringNo
media[].metadata[].is_requiredbooleanNo
is_visiblebooleanNo
is_activebooleanNo
is_featuredbooleanNo
tagsstring[]No
typeenumNoValues: COLLECTION, SAVED_SEARCH, CATEGORY
parent_idstringNo
metadataCommerceMetadata[]No
metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
metadata[].valueobjectNoThe field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES_NO as true/false; MULTIPLE_SELECT as an array of option values; otherwise a string.
metadata[].namespacestringNo
metadata[].formatenumNoThe data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNo
metadata[].slugstringNoThe integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.
metadata[].descriptionstringNo
metadata[].is_requiredbooleanNo
item_metadataCommerceMetadata[]No
item_metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
item_metadata[].valueobjectNoThe field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES_NO as true/false; MULTIPLE_SELECT as an array of option values; otherwise a string.
item_metadata[].namespacestringNo
item_metadata[].formatenumNoThe data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
item_metadata[].extra_dataobjectNo
item_metadata[].slugstringNoThe integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.
item_metadata[].descriptionstringNo
item_metadata[].is_requiredbooleanNo

TypeScript

TypeScript
export type CommerceCollection = {
	id?: string;
	created_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	updated_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	name: string; // The collection's name
	public_name?: string;
	description?: string;
	public_description?: string;
	media?: [];
	is_visible?: boolean;
	is_active?: boolean;
	is_featured?: boolean;
	tags?: string[];
	type?: 'COLLECTION' | 'SAVED_SEARCH' | 'CATEGORY';
	parent_id?: string;
	metadata?: [];
	item_metadata?: [];
	raw?: any;
}

Zod

Zod
import { z } from 'zod';

export const ZodCommerceCollection = z.object({
	id: z.string().optional(),
	created_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	updated_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	name: z.string().describe("The collection's name"),
	public_name: z.string().optional(),
	description: z.string().optional(),
	public_description: z.string().optional(),
	media: z.array().optional(),
	is_visible: z.boolean().optional(),
	is_active: z.boolean().optional(),
	is_featured: z.boolean().optional(),
	tags: z.array().optional(),
	type: z.enum("COLLECTION", "SAVED_SEARCH", "CATEGORY").optional(),
	parent_id: z.string().optional(),
	metadata: z.array().optional(),
	item_metadata: z.array().optional(),

});

Python

Python
import dataclasses

@dataclasses.dataclass
class CommerceCollectionType(str, Enum):
	COLLECTION = 'COLLECTION'
	SAVED_SEARCH = 'SAVED_SEARCH'
	CATEGORY = 'CATEGORY'

@dataclasses.dataclass
class CommerceCollection:
	id: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	created_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	updated_at: Optional[str]
	"""The collection's name"""
	name: str
	public_name: Optional[str]
	description: Optional[str]
	public_description: Optional[str]
	media: Optional[PropertyCommerceCollectionMedia]
	is_visible: Optional[bool]
	is_active: Optional[bool]
	is_featured: Optional[bool]
	tags: Optional[List[List[str]]]
	type: Optional[CommerceCollectionType]
	parent_id: Optional[str]
	metadata: Optional[PropertyCommerceCollectionMetadata]
	item_metadata: Optional[PropertyCommerceCollectionItem_metadata]
Are we missing anything? Let us know
Was this page helpful?