Shopify Lists

This guide shows how to build a wishlist on a Shopify storefront with Omneo Lists. It covers reading a customer’s lists, creating the wishlist on first save, adding items, generating a share code, and reading a shared list. The code runs from a Shopify Liquid theme or App UI Extension.

This guide assumes you already have an Omneo ID Proxy token. See Shopify Authentication for how to obtain one.

Prerequisites

Requirement	Details
ID Proxy token	Obtained from `/apps/cx` in a Liquid theme, or your Remix route in a UI Extension. See Shopify Authentication.
List Definition	At least one list definition (for example, a wishlist) configured in Omneo, with `allow_new` enabled, and `allow_share` enabled if lists will be shared. See List Definitions.
Product sync	Products synced from Shopify, so list items resolve to Omneo products. See Product sync.
SDK	The `@omneo/omneo-sdk` package installed in your Shopify app or theme bundle.

Initialise the SDK

Construct an ID client with the token, tenant, and expiry returned from the auth flow.

import { ID } from '@omneo/omneo-sdk'

const client = new ID({
  tenant,
  IDToken: token,
  IDTokenExpiry: exp
})

All client.profile.* calls are scoped to the customer the token was issued for.

Fetch a customer’s lists

Return all lists associated with the logged-in profile.

const lists = await client.profile.lists.list()

lists is an array of list objects. Each list includes its id, its own handle, its list definition, items, and metadata. If the customer has no lists yet, the array is empty.

Create the wishlist on first save

Omneo does not create a list automatically. Adding an item to a list the customer does not have returns 404. Create the list the first time the customer saves an item, then reuse it. A customer can hold more than one list of the same definition, so look for an existing list before creating one. Give the list a predictable handle so your theme can address it by handle.

const WISHLIST_HANDLE = 'wishlist'

async function getOrCreateWishlist (client, definitionId) {
  const lists = await client.profile.lists.list()
  const existing = lists.find((list) => list.handle === WISHLIST_HANDLE)
  if (existing) return existing

  return client.profile.lists.create({
    name: 'Wishlist',
    handle: WISHLIST_HANDLE,
    list_definition_id: definitionId
  })
}

list_definition_id is the definition’s numeric id. Ids differ between environments, so resolve the id from the definition’s handle for each environment rather than hardcoding one value in your theme.

Add an item

Add items by variant so the customer’s chosen size or colour is saved. With the default product sync, a Shopify variant’s numeric ID is stored on the Omneo variant’s external_id, but external_id on a list item matches products, not variants. Send the variant’s SKU or barcode instead, or the Omneo product_variant_id.

const wishlist = await getOrCreateWishlist(client, definitionId)

await client.profile.lists.items.create(wishlist.id, {
  product_variant_sku: '{{ variant.sku }}'
})

To save a product with no variant, send the Shopify product ID as external_id. This matches the Omneo product’s external_id. See Product List Items for every identifier. Generate a shareable handle for a list by posting to its shares endpoint. Sharing needs the list’s definition to have allow_share enabled.

const share = await client.profile.lists.shares.create(wishlist.id)
const shareCode = share.handle

Sharing is idempotent. Posting again for the same list returns the existing share and the same handle, so the code is stable and safe to show every time the customer opens the share option. Omneo returns the code only, not a URL. Host the shared-list page on your own storefront and put the code in its URL, for example https://www.example.com/pages/shared-list?code={shareCode}.

The Profile Portal shows a customer’s lists but has no share option. To let customers share a wishlist, build the share button and the shared-list page in your theme.

Read a shared list through the ID Proxy’s /lists/shares/{handle} route. It works with an anonymous token from /apps/cx, so recipients who are not logged in, or have no Omneo profile, can still open the list.

const sharedList = await client.call({
  endpoint: `/lists/shares/${shareCode}`,
  method: 'GET'
})

This route returns the list and its items without the owner’s personal data. Each item includes its product and variant, with title, images, price and web_url, for rendering the page. Do not call the Core API’s /v3/lists/shares/{handle} routes from the browser: they need an API token, and the version without /no_profile includes the owner’s profile.

End-to-end example

import { ID } from '@omneo/omneo-sdk'

// token, tenant and exp come from the auth flow
const client = new ID({
  tenant,
  IDToken: token,
  IDTokenExpiry: exp
})

const wishlist = await getOrCreateWishlist(client, definitionId)

await client.profile.lists.items.create(wishlist.id, {
  product_variant_sku: 'SKU-123'
})

const { handle: shareCode } = await client.profile.lists.shares.create(wishlist.id)

// On the shared-list page, with any ID Proxy token (anonymous is fine)
const sharedList = await client.call({
  endpoint: `/lists/shares/${shareCode}`,
  method: 'GET'
})

Working with Product Lists

List creation, identifiers, and sharing behaviour.

List Definitions

Configure list types and their rules.

Shopify Authentication

How to obtain the ID Proxy token used by this guide.

Lists API reference

Endpoint-level reference for lists, items, and shares.

Overview

Ecommerce

Communications

ERP and POS

Customer service

Gift cards and stored value

Currency and regions

Prerequisites

Initialise the SDK

Fetch a customer’s lists

Create the wishlist on first save

Add an item

End-to-end example

Further reading

Working with Product Lists

List Definitions

Shopify Authentication

Lists API reference

​Prerequisites

​Initialise the SDK

​Fetch a customer’s lists

​Create the wishlist on first save

​Add an item

​Generate a share code

​Fetch a list by share code

​End-to-end example

​Further reading

Working with Product Lists

List Definitions

Shopify Authentication

Lists API reference

Prerequisites

Initialise the SDK

Fetch a customer’s lists

Create the wishlist on first save

Add an item

Generate a share code

Fetch a list by share code

End-to-end example

Further reading