Update a collection model
const url = 'https://acme.mykreezalid.com/api/v1/collection-models/example?by=handle';const options = { method: 'PATCH', headers: {Authorization: 'Basic <credentials>', 'Content-Type': 'application/json'}, body: '{"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"}]},"sort_by":"alphabetical","hide_empty":false,"handle_pattern":"voitures-{value}","title_pattern":"Voitures {value}","page_title":"Voitures {value} d\'occasion","subtitle":"example","description":"example","image_alt":"example","template":"example","thumbnail":"example","meta_title":"example","meta_description":"example","meta_keywords":"example","no_index":false,"no_follow":false,"sitemap_changefreq":"example","sitemap_priority":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url 'https://acme.mykreezalid.com/api/v1/collection-models/example?by=handle' \ --header 'Authorization: Basic <credentials>' \ --header 'Content-Type: application/json' \ --data '{ "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" } ] }, "sort_by": "alphabetical", "hide_empty": false, "handle_pattern": "voitures-{value}", "title_pattern": "Voitures {value}", "page_title": "Voitures {value} d'\''occasion", "subtitle": "example", "description": "example", "image_alt": "example", "template": "example", "thumbnail": "example", "meta_title": "example", "meta_description": "example", "meta_keywords": "example", "no_index": false, "no_follow": false, "sitemap_changefreq": "example", "sitemap_priority": 1 }'Changes the fields sent, then brings its collections in step: conditions rewritten, new values’ collections created, those of values taken out put offline, those of values put back online. pivot is the whole criterion: sent, it replaces the previous one, values in their new order. A model that has collections keeps its type. With dry_run=1, nothing is written.
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.
1 to preview, writing nothing
Request Bodyrequired
Section titled “Request Bodyrequired”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
Example
3Internal handle, unique among models: a model has no page, so it holds no address of the site
Example
voitures-par-marqueThe model’s own name
Example
Voitures par marqueWhat its collections present
The conditions every collection shares, all of them met: inclusion {type: AND, rules: […]} and exclusion […]
object
Example
{ "inclusion": { "type": "AND", "rules": [ { "type": "order_type", "operator": "is", "value": [ "1" ] } ] }}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
Example
{ "type": "attribute", "field": "marque", "values": [ { "value": "12", "label": "Renault" }, { "value": "14", "label": "Peugeot" } ]}The criterion as a person reads it
object
Example
{ "type": "attribute", "field": "marque", "name": "Marque"}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}
Example
voitures-{value}Its collections’ name, with {value}; empty, the value’s label
Example
Voitures {value}Example
Voitures {value} d'occasionHTML
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
Example
432432URL-friendly identifier for the collection (slug)
Example
soldesHuman-readable title of the collection
Example
Promotions de PrintempsFlexible metadata container for the collection
object
Example
{ "last_updated_at": "2025-07-01T10:00:00Z", "theme": "blue"}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}.
Example
promosWhether the collection is a storefront page, at /{handle}
Example
trueWhether its page is online
Example
trueWhat it presents: listing or user
Example
listingThe title its page shows. On a collection made by a model: null for the model’s pattern, empty for nothing, or its own
Example
Voitures électriquesSame three states as page_title
Example
nullHTML; same three states as page_title
Example
nullAlternative text of the image (the image itself is uploaded in the back office)
Example
nullIts conditions: inclusion {type: AND or OR, rules: […]} and exclusion […]. Read-only on a collection made by a model
object
Example
nullSuffix of the theme’s collection template; empty, the default one
Example
nullSnippet drawing each item; empty, the default card of its type
Example
nullFull URL; never inherited
Example
nullSEO title
Example
nullSEO description
Example
nullSEO keywords
Example
nullKept out of search engines; null on a collection made by a model: as the model
Example
falseLinks not followed; null on a collection made by a model: as the model
Example
falseAlways, hourly, daily, weekly, monthly, yearly or never
Example
nullFrom 0 to 1
Example
nullThe id of the collection model it is made by; read-only
Example
nullThe handle of that model; read-only
Example
nullThe model’s value it stands for; read-only
Example
nullThe label of that value; read-only
Example
nullThe criterion its model varies on: type, field (an attribute’s alias) and a readable name
object
Example
{ "type": "attribute", "field": "marque", "name": "Marque"}Collection creation date
Example
2025-07-20T10:30:00ZDate of last update
Example
2025-07-20T14:45:00ZResponses
Section titled “Responses”model, and plan, the changes carried out (or that would be)
A collection model as saved (or as it would be), and the changes to its collections
object
True when nothing was written
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
One change per collection concerned; a collection already in step is not in it
What saving a model does to one of its collections
object
Create: a new value’s collection; update: its conditions rewritten; online: a value put back; offline: a value taken out (its texts kept)
The collection’s handle
The collection’s id; null for one still to create
For a create whose address was held: what held it. The collection then takes the first free -2, -3…
For a create: the address the pattern gave
Example
{ "model": { "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" } ] }, "plan": [ { "action": "create", "value": "12", "label": "Renault", "handle": "voitures-renault", "reason": "page", "wanted": "voitures-renault" } ]}Invalid: errors lists every problem, or 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"}