---
title: "Create or replace products"
method: POST
path: "/v1/catalog/products"
tags: ["Products"]
---

# Create or replace products

`POST /v1/catalog/products`

You can create different types of products, such as simple products and configurable products.

When creating products:
 - Each product requires a unique SKU identifier.
 - Products must have a defined catalog source, for example `locale`.
 - Add values for the required `name`, `slug`, and `status` fields.
 - Define optional fields such as descriptions, images, and custom attributes as needed.
 - Use the `links` field to define relationships between products, such as linking a product variant to its parent
 configurable product.
 - You can create multiple products in a single request, and also create product variants for configurable products in the same request.
 - Use the `routes` field to set category paths. The `path` value must match an existing category slug, for example `men/clothing`. 
 - Create a route for each category path. For example to include a product in each of the following categories `men`, `men/clothing`, and `men/clothing/pants`, specify three `path` values, one for each category.

<h3 id="simpleProducts">Simple products</h3>
Create products or replace existing products with specified `sku` and `source` values.

Use the <strong>[update operation](#operation/updateProducts)</strong> to modify values for an existing product.

<h3 id="configurableProducts">Configurable products</h3>

A configurable product is a parent product that allows customers to select from multiple predefined attributes such as color, size, and material.
Each unique combination of these attribute values (for example, `color=green`, `size=large`) represents a product variant.

Each variant is treated as a distinct child product with its own SKU, price, and inventory. These variants are stored as separate entities in the database and linked to the parent configurable product.

The configurable product itself acts as a container or abstraction layer, enabling a unified frontend experience while maintaining
granular control over each variant on the backend.

To create a configurable product, you need the following:

* <strong>Product attributes</strong>—<a href="#operation/createProductMetadata">Create product attributes</a> (for example, "color", "size")
that will be used to differentiate product variants. These attributes must be registered in the system before they can be referenced in
product definitions.

* <strong>Configurable product</strong>—Define the parent product and include a
  [configurations](#operation/createProducts!path=configurations&t=request) array that specifies the selectable options
  and maps each option to a set of possible values. Each value must include a
  [variantReferenceId](#operation/createProducts!path=configurations/values/variantReferenceId&t=request),
  which links to a specific variant.

* <strong>Product variants</strong>—Define a product variant for each valid combination of attribute values. Each variant must:
  * Include relevant attribute values in an [attributes](#operation/createProducts!path=attributes&t=request) array.
  * Reference the parent configurable product using variantReferenceId.
  * Include a [links](#operation/createProducts!path=links&t=request) array with a link of type `VARIANT_OF` pointing to the configurable product.

  For example:

  <pre>
  {
    "sku": "pants-red-32",
    "attributes": [
      {
        "code": "color",
        "values": ["Red"],
        "variantReferenceId": "pants-color-red"
      }
    ],
    "links": [
      {
        "type": "VARIANT_OF",
        "sku": "pants"
      }
    ]
  }
</pre>

  Each product variant links back to the configurable product through its `variantReferenceId`, which corresponds to specific `configurations[].values[].variantReferenceId` in the configurable product.

  To unassign a product variant from a configurable product, do one of the following:
  - Use [Delete Product API](#operation/deleteProducts) to delete the product variant.
  - Use [Update Product API](#operation/updateProducts) to set the ["variantReferenceId"](#operation/createProducts!path=attributes/variantReferenceId&t=request) to `null` and unassign the product variant from the configurable product by removing the ["links"](#operation/createProducts!path=links&t=request) association.

<h3>Bundle products</h3>

A bundle product combines several simple products into one sellable unit. Items within the bundle can be categorized into logical groups like `tops`, `bottoms`, and `accessories`.
Each group can have multiple items, and shoppers can select items from each group to create a customized bundle.

To create a bundle product, you need the following:

* <strong>Bundle product</strong>—[Define the parent product](#operation/createProducts) and include a [bundles](#operation/createProducts!path=bundles) array that
specifies the groups and items included in the bundle. Each group must define:
  * `group` - Name of the group (for example, "tops", "bottoms")
  * `required` - Whether a selection from this group is mandatory
  * `multiSelect` - Whether multiple items can be selected
  * `items` - List of products that can be selected from this group

* <strong>Simple products</strong>—Define each simple product to include in the bundle. Each product must:
  * Include a [links](#operation/createProducts!path=links) array with a link of type `IN_BUNDLE` pointing to the bundle product
  * Be created separately using the [create product API](#operation/createProducts)

<strong>Note:</strong> A simple product can be included only once in each bundle.
If the same item is specified in multiple groups, the API returns a `Duplicate SKU found in bundle items` error.

To update a bundle product, do one of the following:
* Use the [Update products API](#operation/updateProducts) to modify the groups and items in the bundle
* Use the [Delete products API](#operation/deleteProducts) to remove items from the bundle

## Headers

- `Authorization` string, required — Authorization Bearer token
- `Content-Type` 'application/json', required
- `Content-Encoding` 'gzip'

## Request body

- FeedProduct[]
  - `sku` string, required — SKU (Stock Keeping Unit) is a unique identifier for a product.
  - `source` Source, required — Source of the entity, for example, "en-US" for US English.
    - `locale` string, required — A single value that represents content locale, for example, English.
  - `name` string, required — Product name
  - `slug` string, required — The URL key for the product.
  - `description` string, nullable — The main description for the product
  - `shortDescription` string, nullable — A short description of the product
  - `status` 'ENABLED' | 'DISABLED', required — Indicates whether the product is visible on the storefront. The value is "Enabled" if it is visible, and "Disabled" if it is not visible.
  - `visibleIn` string[] — Storefront area where the product is visible. An empty list means that it is not visible as a stand alone product. * `CATALOG`: Product is visible on Product Listing Page and Product Detail Page. * `SEARCH`: Product is visible on Search Results Page and Product Detail Page.
  - `metaTags` ProductMetaAttribute — Meta attributes that are specified in <meta> tags.
    - `title` string — A meta title
    - `keywords` string[] — A meta keywords
    - `description` string — A meta description
  - `attributes` ProductAttribute[] — A list of product attributes.
    - `code` string, required — Product Attribute Code
    - `values` string[], required — A list of value(s) associated with a specified attribute code.
    - `variantReferenceId` string, nullable — The variant reference ID establishes a link between a product variant and the corresponding [Option Value ID](#operation/createProducts!path=options/values/id&t=request) in a configurable product. A variant reference ID can be specified only for a product that represents a variant of a configurable product.
  - `images` ProductImage[] — A list of product images.
    - `url` string, required — Media resource URL
    - `label` string — Media resource label
    - `roles` string[] — Roles associated with this image that determine how the image is used on the storefront. - `BASE`: Product image is visible as a main image on the Product Detail Page. - `SMALL`: Product image is visible as a main image on the Category or search result page or other product listing pages. - `THUMBNAIL`: Thumbnail images appear in the thumbnail gallery, shopping cart, etc. - `SWATCH`: A swatch can be used to illustrate the color, pattern, or texture.
    - `customRoles` string[] — Custom image role. Merchants can define custom roles in addition to the predefined values.
  - `links` ProductLink[] — A list of linked SKUs.
    - `type` string, required — Product link type. Merchants can define custom types in addition to the predefined values. - `VARIANT_OF` link type must be specified to establish a connection to the configurable product SKU. - `IN_BUNDLE` link type must be specified to establish a connection to the bundle product SKU.
    - `sku` string, required — Product SKU
  - `routes` ProductRoutes[] — A list of product routes.
    - `path` string, required — URL path
    - `position` integer — Position of a product in the URL path. The default value is 0.
  - `configurations` ProductConfiguration[] — Composite products, such as configurable products, must provide a list of product options that a shopper can select (for example, "color", "size", etc.).
    - `attributeCode` string, required — Product option attribute code. For `CONFIGURABLE` or `SWATCH` option types, this ID must match the ["attribute code"](#operation/createProducts!path=attributes/code&t=request) used for the configurable product (for example, "color").
    - `label` string — Option label
    - `defaultVariantReferenceId` string, nullable — Specifies the pre-selected value variant reference id of the current option.
    - `type` 'CONFIGURABLE' | 'SWATCH', required — Option type. Indicates the product type the option can be assigned to. - `CONFIGURABLE`: Configurable product option - `SWATCH`: Swatch product option. Must be used for color or text swatches attributes
    - `values` ProductOptionValue[], required — A list of option values. Defines option values available to shoppers (for example, "red" color or "large" size).
      - `variantReferenceId` string, required — Option value ID. For `CONFIGURABLE` or `SWATCH` option types, this ID must match the ["variantReferenceId"](#operation/createProducts!path=attributes/variantReferenceId&t=request) defined in the product variant.
      - `label` string — Option value label
      - `colorHex` string — A hex representation of the color of the option value. Can be used for option with a SWATCH type.
      - `imageUrl` string — Image URL of the option value. Can be used for option with a SWATCH type.
  - `bundles` ProductBundle[] — Composite products, such as bundle products, must include a list of individual products that are part of the bundle, organized into groups (for example, "shirts", "pants", "accessories").
    - `group` string, required — Name of the group that organizes the bundle items. This helps in categorizing the items within the bundle for better organization. For example, groups can be "shirts", "pants", "accessories", etc.
    - `required` boolean — Indicates whether a shopper is required to select any products from this group to add the bundle to the shopping cart.
    - `multiSelect` boolean — Indicates whether multiple products can be selected by a shopper.
    - `defaultItemSkus` string[] — A list of default product SKUs that are selected in this bundle group.
    - `items` ProductBundleItem[], required — A list of individual products that are part of the bundle. Each item in the list represents a product that can be selected as part of the bundle.
      - `sku` string, required — Product SKU of the bundle item.
      - `qty` number, float — Quantity of the item in the bundle.
      - `userDefinedQty` boolean — Indicates whether the quantity of the item in the bundle can be defined by a shopper.
  - `externalIds` ProductExternalId[] — A list of external IDs for the product.
    - `id` string, required — External ID of the product.
    - `origin` string, required — External ID origin. Specifies the system that generated the external ID, such as Adobe Commerce, Google Product Ratings, etc.

## Response `200`

All items accepted and will be processed asynchronously

## Other responses

- `400` — Some of the received items are invalid. Check the "message" and "errors" fields for details. Common causes of validation errors include: * **Invalid SKU**: SKU does not exist in the catalog * **Invalid Price Book**: Price book ID does not exist * **Invalid Discount Code**: Duplicate or invalid discount codes * **Invalid Tier Quantities**: Quantities not in ascending order or less than 2 * **Configurable Product Price**: Attempting to set price for configurable product SKU * **Invalid Price Format**: Non-numeric or negative price values * **Incorrect Category Slug**: Invalid category slug format * **Incorrect hierarchy configuration**: Misconfiguration of price book parent-child relationship
- `401` — Verify that the Bearer token provided in the `Authorization` header is still valid.
- `403` — Verify that the `Authorization` header is present, and that the Bearer token is still valid.
- `429` — Indicates that a client has exceeded the rate limit of 300 requests per minute. Check the `retry-after` header to get the time (in seconds) to wait before sending the next request.

---

[API](https://skmtc.dev/adobe/apis/catalog-data-ingestion-api.md) · [All operations](https://skmtc.dev/adobe/apis/catalog-data-ingestion-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/adobe/catalog-data-ingestion-api/revisions/ca8c8f2680fe/schema)