Create or update a sub-collection
const url = 'https://acme.mykreezalid.com/api/v1/collections/example';const options = { method: 'POST', headers: {Authorization: 'Basic <credentials>', 'Content-Type': 'application/json'}, body: '{"handle":"spring-sale","title":"Spring sale","metadata":{"theme":"blue"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://acme.mykreezalid.com/api/v1/collections/example \ --header 'Authorization: Basic <credentials>' \ --header 'Content-Type: application/json' \ --data '{ "handle": "spring-sale", "title": "Spring sale", "metadata": { "theme": "blue" } }'Creates a sub-collection under an existing collection. If a collection with this handle already exists under the same parent, its title and metadata are updated instead (metadata only when sent) and 200 is returned. A handle already used under another parent is refused with 400. A handle that is not lowercase letters, digits and dashes is kept as your own code and a URL-safe handle is derived from it; later calls may use either.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The handle of the parent collection, or your own code for it
Request Bodyrequired
Section titled “Request Bodyrequired”object
Lowercase letters, digits and dashes, or your own code (see above)
Example
spring-saleExample
Spring saleYour own data, as an object or a JSON string
object
Example
{ "theme": "blue"}Responses
Section titled “Responses”A collection with this handle already existed under the same parent: it has been updated
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": 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"}The collection has been created
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": 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"}The handle is missing or has no letter or digit, it is already used under another parent, or the collection could not be saved
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"}Parent collection 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"}