How lists work
Lists follow a Definition/Instance pattern:- List Definition: defines the type of list (name, handle, type, and rules like whether items can be reserved or shared)
- Product List: an instance of a definition, linked to a profile and containing items
Lists are not created automatically
A list must exist before items can be added to it. Adding an item to a list the profile does not have returns404. It does not create the list. For a wishlist, create the customer’s list the first time they save an item, then add items to it.
A profile can hold more than one list of the same definition. Before creating a list, read the profile’s lists and reuse the one you want.
Creating a product list
Creating a list against a definition with
allow_new: false returns 422.
List identifiers in paths
Profile list routes take a list identifier in the path, shown as{list} or {handle} in the API reference.
The handle in these paths is the list’s handle, not the list definition’s handle.
Reading all lists for a profile
Reading a specific list
Updating a list
Sharing a list
If the list’s definition hasallow_share enabled (the default), the list can be shared. Sharing returns a share record whose handle is the share code to pass to others:
- Sharing is idempotent. Posting again for the same list returns the existing share and the same
handle, so the share code is stable. - Omneo returns the share code only, not a URL. Build the share link on your own site, for example
https://www.example.com/pages/shared-list?code={handle}. - If the definition has
allow_share: false, the request returns an error.
Getting a shared list by share code
There are two read endpoints. They differ in how much of the owner’s data they return:
Both endpoints are Core API routes that need an API token, so call them server-side only. In a browser, read shared lists through the Omneo ID Proxy instead. Its
GET /lists/shares/{shareCode} route returns the no-profile view and accepts an anonymous token. See Shopify Lists.