# Create a product
> Create a new product in your catalog.
{/* generated:versioned-pages - edit _pm-authored, not this file */}
`POST /api/products`
Creates a Product resource.
Creates a single product in the current organization. The product is returned with all read-only fields (id, timestamps, derived state) populated. You can also create initial channel assignments, collections and variants in the same call.
> **Default status**
>
> New products are created in their default status (typically `draft`). Promote them to `active` with a `PATCH` once they're ready to surface to your channels.
## 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 |
| ------------- | ----------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attributes` | `ProductAttributeValueResource[]` | - | Attribute values for the attribute definitions attached to the product's category (or one of its ancestors). |
| `category` | `string \| null` | - | Category IRI this product is attached to. Categories drive the attribute set. Requires the `categories:read` scope. Returned null when the scope is missing. |
| `channels` | `string[]` | - | A list of `Channel` IRIs the product is assigned to. Requires the `channels:read` scope. Returned empty when the scope is missing. |
| `collections` | `string[]` | - | A list of `Collection` IRIs the product is attached to. Requires the `collections:read` scope. Returned empty when the scope is missing. |
| `description` | `string \| null` | - | Long-form description. Markdown is not parsed by the API. |
| `medias` | `string[]` | - | A list of `Media` IRIs (ordered). Only images are accepted. Position determines display order. Requires the `medias:read` scope. Returned empty when the scope is missing. |
| `status` | `"/api/statuses/DRAFT" \| "/api/statuses/ACTIVE" \| "/api/statuses/ARCHIVED"` | - | Status IRI controlling visibility. Optional - defaults to a draft status when omitted. |
| `tags` | `string \| null` | - | Comma-separated list of free-form tags. Used for storefront filtering. |
| `title` | `string \| null` | - | Customer-facing product title. Translatable - set the active locale with `Flowkiwi-Locale`. |
## Response
**201** - Product resource created
| Property | Type | Required | Description |
| ------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@context` | `string \| object` | - | |
| `@id` | `string` | Yes | |
| `@type` | `string` | Yes | |
| `attributes` | `ProductAttributeValueResource[]` | - | Attribute values for the attribute definitions attached to the product's category (or one of its ancestors). Each item references a `definition` (IRI) plus either an `option` (for `list` definitions) or a `value` (for `string` definitions). |
| `category` | `string \| Category \| null` | - | The category to which this product belongs. Serialized as IRI string by default; pass `?expand=category` to embed the full `CategoryResource`. Requires the `categories:read` scope. Returned null when the scope is missing. |
| `channels` | `array` | - | A list of `Channel`, each one representing a channel associated with the product. Serialized as IRI strings by default; pass `?expand=channels` to embed full `ChannelResource` objects. Requires the `channels:read` scope. Returned empty when the scope is missing. |
| `collections` | `array` | - | A list of `Collection`, each one representing a collection associated with the product. Serialized as IRI strings by default; pass `?expand=collections` to embed full `CollectionResource` objects. 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). |
| `description` | `string \| null` | - | **This property supports translations.**
A description of the product. |
| `id` | `string` | - | Stable UUID of the product. |
| `medias` | `array` | - | A list of `Media`, ordered by position. Only media of type "image" can be associated with a product. Returned as IRI strings by default; pass `?expand=medias` to embed full `Media` objects. Requires the `medias:read` scope. Returned empty when the scope is missing. |
| `metafields` | `array` | - | Metafields owned by this product. Serialized as IRI strings by default; pass `?expand=metafields` to embed full `MetafieldResource` objects. Requires the `metafields:read` scope. Returned empty when the scope is missing. |
| `options` | `array` | - | A list of `Product Option`, each one representing an option associated with the product. Serialized as IRI strings by default; pass `?expand=options` to embed the full `Product Option` objects. 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 product. |
| `tags` | `string \| null` | - | A string of comma-separated tags. |
| `title` | `string \| null` | - | **This property supports translations.**
The name of the product. |
| `updatedAt` | `string` | - | The date and time when the resource was last modified (ISO 8601 format). |
| `variants` | `array` | - | A list of `Variant`, each one representing a variant associated with the product. Serialized as IRI strings by default; pass `?expand=variants` to embed the full `Variant` objects (including `resolvedPrice`, `lowestPriceLast30Days`, `medias`, and `metafields` when composed with `?expand=metafields`). Requires the `products:read` scope. Returned empty when the scope is missing. |
## Errors
**400** - Invalid input
| Property | Type | Required | Description |
| ------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@context` | `string \| object` | - | |
| `@id` | `string` | Yes | |
| `@type` | `string` | Yes | |
| `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.
| Property | Type | Required | Description |
| -------------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `@context` | `string \| object` | - | |
| `@id` | `string` | Yes | |
| `@type` | `string` | Yes | |
| `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` | Yes | |
| `@type` | `string` | Yes | |
| `description` | `string` | - | |
| `detail` | `string` | - | |
| `instance` | `string \| null` | - | |
| `status` | `integer` | - | |
| `title` | `string \| null` | - | |
| `type` | `string` | - | |
| `violations` | `object[]` | - | |
## Examples
### Example request
```bash
curl -X POST 'https://.product-management.flowkiwi.net/api/products' \
-H 'Authorization: Bearer {access_token}' \
-H 'Flowkiwi-Api-Version: unstable' \
-H 'Accept: application/ld+json' \
-H 'Content-Type: application/ld+json' \
-d '{
"category": "/api/categories/189da995-59a7-5a6e-a1f3-42718ff4992e",
"channels": [
"/api/channels/65d94da2-dc93-52cc-9055-e2d096dd3a8b"
],
"collections": [
"/api/collections/05607b06-ebb2-5b6e-b7cb-4a372874ef4f"
],
"description": "Comfortable and sustainable t-shirt made from 100% organic cotton",
"status": "/api/statuses/ACTIVE",
"tags": "organic,sustainable,cotton,premium",
"title": "Premium Organic Cotton T-Shirt"
}'
```
### Example response
```json
{
"@context": "/api/contexts/Product",
"@id": "/api/products/8aa97de5-261a-5a5d-bb5e-3453d4356f07",
"@type": "Product",
"attributes": [],
"category": null,
"channels": [],
"collections": [],
"createdAt": "2024-01-01T00:00:00+00:00",
"description": "Comfortable and sustainable t-shirt made from 100% organic cotton. Available in multiple colors.",
"id": "8aa97de5-261a-5a5d-bb5e-3453d4356f07",
"medias": [],
"options": [],
"status": "/api/statuses/DRAFT",
"tags": "organic,sustainable,cotton,apparel",
"title": "Premium Organic Cotton T-Shirt",
"updatedAt": "2024-01-01T00:00:00+00:00",
"variants": []
}
```