List Definitions

A List Definition is the configuration template for a type of product list. It defines the rules that all lists of that type will follow, whether items can have quantities, whether the list can be shared, and whether items can be reserved.

List definition fields

Field	Required	Default	Description
`name`	Yes		Display name for the list type
`handle`	Yes		Unique slug identifier. Not accepted on update.
`type`	Yes		Free-form category string for grouping (for example `wishlist`)
`short_description`	No		Brief description shown to customers
`description`	No		Full description
`icon`, `cover`	No		Display assets for the list type
`allow_new`	No	`true`	Whether new lists can be created from this definition. Creating a list against a definition with `allow_new: false` returns `422`.
`allow_edit`	No	`true`	Whether lists of this type can be edited
`allow_delete`	No	`true`	Whether lists of this type can be deleted
`allow_share`	No	`true`	Whether lists of this type can be shared. Creating a share on a list whose definition has `allow_share: false` returns an error.
`allow_quantity`	No	`false`	Whether items store a quantity (for example “2 of this item”). When `false`, any `quantity` sent on an item is ignored.
`allow_reserve`	No	`false`	Whether others can reserve items on shared lists. See List reservations.
`allow_custom_product`	No	`false`	Whether custom (non-catalogue) items can be added through the `/custom` endpoint
`is_published`	No	`false`	Publication flag for surfaces that display list types
`is_active`	No	`false`	Active flag for surfaces that display list types
`meta`	No		Free-form metadata
`tags`	No		Array of tags for filtering

is_published and is_active are not checked when a list is created or an item is added through the API. Use allow_new to stop new lists being created from a definition.

Definitions that support reservations also carry reservation expiry and notification fields (timezone, reservation_period, reservation_period_type, reservation_absolute_expiry and the reservation targets). See List reservations.

Creating a list definition

curl -X POST https://api.[tenant].getomneo.com/api/v3/lists/definitions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wishlist",
    "handle": "wishlist",
    "type": "wishlist",
    "short_description": "Save items you love",
    "allow_share": true,
    "allow_quantity": false,
    "allow_reserve": true,
    "allow_custom_product": false,
    "is_published": true,
    "is_active": true
  }'

Note the id, you will need it when creating customer lists.

Reading a list definition

GET /api/v3/lists/definitions/{definitionId}

Updating a list definition

curl -X PUT https://api.[tenant].getomneo.com/api/v3/lists/definitions/{definitionId} \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_reserve": false
  }'

Deleting a list definition

DELETE /api/v3/lists/definitions/{definitionId}

Deleting a List Definition will affect all product lists that use it. Only delete definitions that have no active lists.

Common definition types

Type	allow_share	allow_reserve	allow_quantity	Use case
`wishlist`	true	true	false	Customer-built wishlist for gifting
`gift-registry`	true	true	true	Bridal/baby registry with quantities
`hold`	false	false	false	In-store hold list visible to staff
`style-edit`	false	false	false	Stylist-curated list for a client

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

Discovery search

POS integration

Appointments

Lists

Groups

Feedback

Extensions

List definition fields

Creating a list definition

Reading a list definition

Updating a list definition

Deleting a list definition

Common definition types

​List definition fields

​Creating a list definition

​Reading a list definition

​Updating a list definition

​Deleting a list definition

​Common definition types

List definition fields

Creating a list definition

Reading a list definition

Updating a list definition

Deleting a list definition

Common definition types