Concepts
If you have used Views in Drupal, the Query Loop block in WordPress, or a query builder in any CMS, most of this will feel familiar. The one idea that is specific to Shopify is that results are stored in metafields rather than rendered by the app.
The index
Shopify's API can fetch metaobjects by type and sort them by a handful of keys, but it cannot filter on field values, follow references, or sort on a field. So the app keeps a copy of your metaobject definitions and entries in its own database and runs list queries there.
The copy is the app's only data. Shopify stays the source of truth: the app never edits an entry, and the copy can be rebuilt from Shopify at any time with Sync now.
A list
A list is a saved query. It has:
- A source: one metaobject type.
- Conditions: any number, on any field of the type, on the entry a reference points at, or in nested all/any groups.
- Sort: one or more keys, including any field, display name, handle, last updated, or random.
- Size: a limit and an offset.
- A context: where the list is written, see below.
- Notes: free text for the next developer.
Draft entries are excluded unless you tick Include drafts.
Contexts
A list is written to one of four places.
| Context | Written to | Typical use |
|---|---|---|
| Store-wide | One metafield on the shop | Featured books, events in the next 30 days |
| Per product | One metafield on each product that a matching entry references | Reading lists that include this book |
| Per collection | One metafield on each collection | Guides for this category |
| Per entry | One JSON map on the shop, keyed by entry handle | The rest of the series, on a book's page |
| Per referenced entry | One JSON map on the shop, keyed by the referenced entry's handle | Books by this author on the author page |
Per-product and per-collection lists need a field on the type that references products or collections. You choose the field in Where it shows. Per-entry lists need a field both entries share, such as a series, and list the other entries that reference the same value. Per-referenced-entry lists turn a reference around: for each author the books reference, the books that point at that author, ready for the author's own page.
Metafields
Every list metafield lives in the lists namespace with the list's handle as the key. Store-wide, per-product and per-collection lists are list.metaobject_reference metafields with a definition the app creates, so they appear in the admin and in the theme editor's dynamic source picker. Per-entry and per-referenced-entry lists are a json metafield holding a map from a handle to an array of entry handles, up to 20 each.
A metafield holds at most 250 entries, and Liquid renders the first 50 of them. Beyond that the list is cut at the limit you set, or at 250; for storefront pages longer than 50, make further lists with an offset.
Freshness
The app subscribes to create, update and delete webhooks for each type you have a list on. When an entry changes, the copy is updated and every list on that type is re-evaluated and, if its result changed, rewritten. This usually takes under fifteen seconds. Metafields are only written when the result differs from the last write, so a busy store does not generate needless updates.
A nightly sweep re-syncs every type as a safety net against missed webhooks. Sync now does the same on demand.
Rendering is yours
The app writes no markup to your storefront and has no theme block. The editor writes a plain Liquid loop for you to adapt, and per-product lists can be bound to your theme's own blocks as dynamic sources. This is deliberate: a generic list block would always need restyling, and a theme block would need supporting on every theme. Your theme knows how to render a card; the app's job is to say which entries go in it.
Uninstall
Uninstalling removes the app's copy and its webhooks. Your metaobjects are untouched. The metafields the app wrote and the definitions it created stay on the store, so the last written lists keep rendering and no template breaks. Delete the definitions under Settings › Custom data if you want them gone.