Create or update collection

POST

/collections

const url = 'https://acme.mykreezalid.com/api/v1/collections';
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 \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "handle": "spring-sale", "title": "Spring sale", "metadata": { "theme": "blue" } }'

Creates a top-level collection. To create a sub-collection, use POST /collections/{parent_handle}. 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

basic

Request Body^required

application/json

object

handle

required

Lowercase letters, digits and dashes, or your own code (see above)

string

Example

spring-sale

title

string

Example

Spring sale

metadata

Your own data, as an object or a JSON string

object

Example

{
  "theme": "blue"
}

Responses

200

A collection with this handle already existed under the same parent: it has been updated

application/json

Collection

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

integer

handle

required

URL-friendly identifier for the collection (slug)

string

title

required

Human-readable title of the collection

string

metadata

Flexible metadata container for the collection

object

parent_handle

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}.

string

nullable

storefront_enabled

Whether the collection is a storefront page, at /{handle}

boolean

is_online

Whether its page is online

boolean

type

What it presents: listing or user

string

page_title

The title its page shows. On a collection made by a model: null for the model’s pattern, empty for nothing, or its own

string

nullable

subtitle

Same three states as page_title

string

nullable

description

HTML; same three states as page_title

string

nullable

image_alt

Alternative text of the image (the image itself is uploaded in the back office)

string

nullable

rules

Its conditions: inclusion {type: AND or OR, rules: […]} and exclusion […]. Read-only on a collection made by a model

object

template

Suffix of the theme’s collection template; empty, the default one

string

nullable

thumbnail

Snippet drawing each item; empty, the default card of its type

string

nullable

canonical_url

Full URL; never inherited

string

nullable

meta_title

SEO title

string

nullable

meta_description

SEO description

string

nullable

meta_keywords

SEO keywords

string

nullable

no_index

Kept out of search engines; null on a collection made by a model: as the model

boolean

nullable

no_follow

Links not followed; null on a collection made by a model: as the model

boolean

nullable

sitemap_changefreq

Always, hourly, daily, weekly, monthly, yearly or never

string

nullable

sitemap_priority

From 0 to 1

number

nullable

model_id

The id of the collection model it is made by; read-only

integer

nullable

model_handle

The handle of that model; read-only

string

nullable

pivot_value

The model’s value it stands for; read-only

string

nullable

pivot_label

The label of that value; read-only

string

nullable

model_pivot

The criterion its model varies on: type, field (an attribute’s alias) and a readable name

object

created_at

Collection creation date

string format: date-time

updated_at

Date of last update

string format: date-time

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"
}

201

The collection has been created

application/json

Collection

object

Collection’s unique identifier

integer

handle

required

URL-friendly identifier for the collection (slug)

string

title

required

Human-readable title of the collection

string

metadata

Flexible metadata container for the collection

object

parent_handle

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}.

string

nullable

storefront_enabled

Whether the collection is a storefront page, at /{handle}

boolean

is_online

Whether its page is online

boolean

type

What it presents: listing or user

string

page_title

The title its page shows. On a collection made by a model: null for the model’s pattern, empty for nothing, or its own

string

nullable

subtitle

Same three states as page_title

string

nullable

description

HTML; same three states as page_title

string

nullable

image_alt

Alternative text of the image (the image itself is uploaded in the back office)

string

nullable

rules

Its conditions: inclusion {type: AND or OR, rules: […]} and exclusion […]. Read-only on a collection made by a model

object

template

Suffix of the theme’s collection template; empty, the default one

string

nullable

thumbnail

Snippet drawing each item; empty, the default card of its type

string

nullable

canonical_url

Full URL; never inherited

string

nullable

meta_title

SEO title

string

nullable

meta_description

SEO description

string

nullable

meta_keywords

SEO keywords

string

nullable

no_index

Kept out of search engines; null on a collection made by a model: as the model

boolean

nullable

no_follow

Links not followed; null on a collection made by a model: as the model

boolean

nullable

sitemap_changefreq

Always, hourly, daily, weekly, monthly, yearly or never

string

nullable

sitemap_priority

From 0 to 1

number

nullable

model_id

The id of the collection model it is made by; read-only

integer

nullable

model_handle

The handle of that model; read-only

string

nullable

pivot_value

The model’s value it stands for; read-only

string

nullable

pivot_label

The label of that value; read-only

string

nullable

model_pivot

The criterion its model varies on: type, field (an attribute’s alias) and a readable name

object

created_at

Collection creation date

string format: date-time

updated_at

Date of last update

string format: date-time

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"
}

400

The handle is missing or has no letter or digit, it is already used under another parent, or the collection could not be saved

application/json

Why a collection or collection model request was refused.

object

success

boolean

message

string

errors

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"
}

Create or update collection

Authorizations

Request Bodyrequired

Example

Example

Example

Responses

200

Example

201

Example

400

Example

Request Body^required