Create a collection

post /api/collections

Creates a Collection resource.

Creates a collection in the current organization. Set its status, optionally a name, optionally nest it under a parent, and attach products in the same call.

Nesting

Set parent to another collection’s IRI to place this collection under it. Leave it unset for a top-level collection.

Headers

Name	Type	Required	Description
Flowkiwi-Locale	string	-	Specifies the locale for properties that support localization. If not provided, the default locale will be used.

Request body

Property	Type	Required	Description
childrens	string[]	-	A list of direct child Collection IRIs nested under this collection. Requires the collections:read scope. Returned empty when the scope is missing.
name	string | null	-	The display name of the collection.
parent	string	-	The parent Collection to which this collection belongs, if any. Requires the collections:read scope. Returned null when the scope is missing.
products	string[]	-	A list of Product IRIs the collection groups together. Requires the products:read scope. Returned empty when the scope is missing.
status	"/api/statuses/DRAFT" | "/api/statuses/ACTIVE" | "/api/statuses/ARCHIVED"	required	The status of the collection.

Response

201 - Collection resource created

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
childrens	array	-	A list of direct child Collection IRIs nested under this collection. Serialized as IRI strings by default; pass ?expand=children to embed direct children (one level only). Requires the collections:read scope. Returned empty when the scope is missing.
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
id	string	-	The resource's unique identifier (UUID).
name	string | null	-	This property supports translations. The display name of the collection.
parent	string | Collection | null	-	The parent Collection to which this collection belongs, if any. Serialized as IRI string by default; pass ?expand=parent to embed the direct parent (one level only). Filter with ?exists[parent]=false to list root collections (no parent) or ?exists[parent]=true for nested ones. Requires the collections:read scope. Returned null when the scope is missing.
products	string[]	-	A list of Product IRIs the collection groups together. Requires the products:read scope. Returned empty when the scope is missing.
status	"/api/statuses/DRAFT" | "/api/statuses/ACTIVE" | "/api/statuses/ARCHIVED"	-	The status of the collection.
updatedAt	string	-	The date and time when the resource was last modified (ISO 8601 format).

Errors

400 - Invalid input

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
code	string	-	Stable identifier of the error in the error code catalogue (see /api/error-codes). Present on catalogued errors only.
description	string | null	-
detail	string | null	-	A human-readable explanation specific to this occurrence of the problem.
instance	string | null	-	A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
message	string	-	End-user message localized in the request locale, with this occurrence's values substituted. Present on catalogued errors only.
slug	string	-	Stable, readable key of the error in the error code catalogue. Present on catalogued errors only.
status	integer | null	-
title	string | null	-	A short, human-readable summary of the problem. For a catalogued error it repeats the slug.
type	string	-	A URI reference that identifies the problem type. For a catalogued error it is the error code resource, /api/error-codes/{code}.

403 - Access denied. The caller is missing one or more permissions required for this operation.

Content-Type: application/problem+json

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
detail	string	-
missingPermissions	string[]	-	Permissions that the caller is missing for this operation. Present only when the 403 is caused by a denied permission.
status	integer	-
title	string	-
type	string	-

422 - An error occurred

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
description	string	-
detail	string	-
instance	string | null	-
status	integer	-
title	string | null	-
type	string	-
violations	object[]	-
Show violations fields Property Type Required Description code string - The code of the violation hint string - An extra hint to understand the violation message string required The message associated with the violation parameters object - Dynamic placeholder values for the violation message template (substitute into the code catalogue message). payload object - The serialized payload of the violation propertyPath string required The property path of the violation slug string - Stable centralized error-code slug for this violation (see /api/error-codes).