Get a collection model and its collections
const url = 'https://acme.mykreezalid.com/api/v1/collection-models/example?by=handle';const options = {method: 'GET', headers: {Authorization: 'Basic <credentials>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://acme.mykreezalid.com/api/v1/collection-models/example?by=handle' \ --header 'Authorization: Basic <credentials>'The model, and its collections in its order (sort_by), as they show: each field a collection leaves unset filled from the model’s pattern. replaced lists the fields a collection sets itself, an empty one included; count how many items it presents.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The model’s handle, or its id with by=id
Query Parameters
Section titled “Query Parameters”How the path names the collection: handle (the default, which also finds an integrator’s source handle) or id. A handle may be made of digits only, so an id is never guessed.
Responses
Section titled “Responses”The model, with collections
A collection model makes one storefront collection per value of a criterion and keeps them in step. Its text fields are patterns: {value} stands for each value’s label. A collection leaving a field unset (null) shows the pattern; one setting it keeps its own.
object
Internal handle, unique among models: a model has no page, so it holds no address of the site
The model’s own name
What its collections present
The conditions every collection shares, all of them met: inclusion {type: AND, rules: […]} and exclusion […]
object
The criterion that varies: type (attribute, category, seller_group, order_type, city, country, department or tag; for users: seller_group, city, country, department), field (an attribute’s alias) and values, in order, each a value and its label. Sent, it replaces the previous criterion whole.
object
The criterion as a person reads it
object
The order of its collections: by label, by how many items each presents (the fullest first), or the order of the values
Whether the theme’s link block (Liquid collection_models.<handle>.collections) leaves out the collections presenting no item, counted every quarter of an hour; their pages stay online
Its collections’ handle, with {value}
Its collections’ name, with {value}; empty, the value’s label
HTML
The image itself is uploaded in the back office
Suffix of the theme’s collection template
Snippet drawing each item
Its collections’ default
Its collections’ default
Always, hourly, daily, weekly, monthly, yearly or never
From 0 to 1
Its collections, in its order: in short in a list of models; as they show (each unset field filled from the pattern, with replaced and count) for one model
Represents a logical group of listings, such as construction projects or promotions, or a storefront page presenting listings or users. A collection made by a collection model follows its model’s conditions; its fields left null show the model’s patterns.
object
Collection’s unique identifier
URL-friendly identifier for the collection (slug)
Human-readable title of the collection
Flexible metadata container for the collection
object
Handle of the parent collection, if this is a sub-collection. It is not returned in responses: list a parent’s sub-collections with GET /collections/{parent_handle}.
Whether the collection is a storefront page, at /{handle}
Whether its page is online
What it presents: listing or user
The title its page shows. On a collection made by a model: null for the model’s pattern, empty for nothing, or its own
Same three states as page_title
HTML; same three states as page_title
Alternative text of the image (the image itself is uploaded in the back office)
Its conditions: inclusion {type: AND or OR, rules: […]} and exclusion […]. Read-only on a collection made by a model
object
Suffix of the theme’s collection template; empty, the default one
Snippet drawing each item; empty, the default card of its type
Full URL; never inherited
SEO title
SEO description
SEO keywords
Kept out of search engines; null on a collection made by a model: as the model
Links not followed; null on a collection made by a model: as the model
Always, hourly, daily, weekly, monthly, yearly or never
From 0 to 1
The id of the collection model it is made by; read-only
The handle of that model; read-only
The model’s value it stands for; read-only
The label of that value; read-only
The criterion its model varies on: type, field (an attribute’s alias) and a readable name
object
Collection creation date
Date of last update
Example
{ "id": 3, "handle": "voitures-par-marque", "title": "Voitures par marque", "type": "listing", "rules": { "inclusion": { "type": "AND", "rules": [ { "type": "order_type", "operator": "is", "value": [ "1" ] } ] } }, "pivot": { "type": "attribute", "field": "marque", "values": [ { "value": "12", "label": "Renault" }, { "value": "14", "label": "Peugeot" } ] }, "criterion": { "type": "attribute", "field": "marque", "name": "Marque" }, "sort_by": "alphabetical", "hide_empty": false, "handle_pattern": "voitures-{value}", "title_pattern": "Voitures {value}", "page_title": "Voitures {value} d'occasion", "no_index": false, "no_follow": false, "collections": [ { "id": 432432, "handle": "soldes", "title": "Promotions de Printemps", "metadata": { "last_updated_at": "2025-07-01T10:00:00Z", "theme": "blue" }, "parent_handle": "promos", "storefront_enabled": true, "is_online": true, "type": "listing", "page_title": "Voitures électriques", "subtitle": null, "description": null, "image_alt": null, "rules": null, "template": null, "thumbnail": null, "canonical_url": null, "meta_title": null, "meta_description": null, "meta_keywords": null, "no_index": false, "no_follow": false, "sitemap_changefreq": null, "sitemap_priority": null, "model_id": null, "model_handle": null, "pivot_value": null, "pivot_label": null, "model_pivot": { "type": "attribute", "field": "marque", "name": "Marque" }, "created_at": "2025-07-20T10:30:00Z", "updated_at": "2025-07-20T14:45:00Z" } ]}by is not handle or id, or with by=id the reference is not a whole number
Why a collection or collection model request was refused.
object
The problems found: for a collection, field by field, the rules not met and their messages. Present only when there are some.
Example
{ "success": false, "message": "Collection handle is required"}Collection model not found
Why a collection or collection model request was refused.
object
The problems found: for a collection, field by field, the rules not met and their messages. Present only when there are some.
Example
{ "success": false, "message": "Collection handle is required"}