Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Catalog Data Ingestion Products API
description: 'The Catalog Data Ingestion API allows you to create and manage products and price books and directly integrate catalog data with the Commerce catalog service.
This API provides the following resource collections to create and update catalog data:
- <strong>[Product Metadata](#tag/ProductMetadata)</strong>—define and manage product attribute metadata including display settings, search characteristics, filtering options, and sorting rules.
- <strong>[Category Metadata](#tag/CategoryMetadata)</strong>—define and manage category attribute metadata.
- <strong>[Categories](#tag/Categories)</strong>—Define and manage categories with hierarchical structure to build navigation menu.
- <strong>[Products](#tag/Products)</strong>—Define and manage catalog items with their attributes (name, description, SKU, images, and variants).
- <strong>[Price books](#tag/Price-Books)</strong>—Define and manage pricing scopes for different customer tiers and markets.
- <strong>[Prices](#tag/Prices)</strong>—Define and manage product SKU prices and their associated price books.
- <strong>[Product Layers](#tag/Product-Layers)</strong>—Define and manage product layers to customize and override base product data for specific contexts, locales, or business requirements.
'
version: 1.0.0
servers:
- url: https://na1-sandbox.api.commerce.adobe.com/{tenantId}
variables:
tenantId:
default: string
tags:
- name: Products
description: Create and manage product data including simple products, configurable products, and their variants. Control product visibility, attributes, images, and pricing
paths:
/v1/catalog/products:
post:
tags:
- Products
summary: Create or replace products
description: "You can create different types of products, such as simple products and configurable products.\n\nWhen creating products:\n - Each product requires a unique SKU identifier.\n - Products must have a defined catalog source, for example `locale`.\n - Add values for the required `name`, `slug`, and `status` fields.\n - Define optional fields such as descriptions, images, and custom attributes as needed.\n - Use the `links` field to define relationships between products, such as linking a product variant to its parent\n configurable product.\n - You can create multiple products in a single request, and also create product variants for configurable products in the same request.\n - Use the `routes` field to set category paths. The `path` value must match an existing category slug, for example `men/clothing`. \n - 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.\n\n<h3 id=\"simpleProducts\">Simple products</h3>\nCreate products or replace existing products with specified `sku` and `source` values.\n\nUse the <strong>[update operation](#operation/updateProducts)</strong> to modify values for an existing product.\n\n<h3 id=\"configurableProducts\">Configurable products</h3>\n\nA configurable product is a parent product that allows customers to select from multiple predefined attributes such as color, size, and material.\nEach unique combination of these attribute values (for example, `color=green`, `size=large`) represents a product variant.\n\nEach 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.\n\nThe configurable product itself acts as a container or abstraction layer, enabling a unified frontend experience while maintaining\ngranular control over each variant on the backend.\n\nTo create a configurable product, you need the following:\n\n* <strong>Product attributes</strong>—<a href=\"#operation/createProductMetadata\">Create product attributes</a> (for example, \"color\", \"size\")\nthat will be used to differentiate product variants. These attributes must be registered in the system before they can be referenced in\nproduct definitions.\n\n* <strong>Configurable product</strong>—Define the parent product and include a\n [configurations](#operation/createProducts!path=configurations&t=request) array that specifies the selectable options\n and maps each option to a set of possible values. Each value must include a\n [variantReferenceId](#operation/createProducts!path=configurations/values/variantReferenceId&t=request),\n which links to a specific variant.\n\n* <strong>Product variants</strong>—Define a product variant for each valid combination of attribute values. Each variant must:\n * Include relevant attribute values in an [attributes](#operation/createProducts!path=attributes&t=request) array.\n * Reference the parent configurable product using variantReferenceId.\n * Include a [links](#operation/createProducts!path=links&t=request) array with a link of type `VARIANT_OF` pointing to the configurable product.\n\n For example:\n\n <pre>\n {\n \"sku\": \"pants-red-32\",\n \"attributes\": [\n {\n \"code\": \"color\",\n \"values\": [\"Red\"],\n \"variantReferenceId\": \"pants-color-red\"\n }\n ],\n \"links\": [\n {\n \"type\": \"VARIANT_OF\",\n \"sku\": \"pants\"\n }\n ]\n }\n</pre>\n\n Each product variant links back to the configurable product through its `variantReferenceId`, which corresponds to specific `configurations[].values[].variantReferenceId` in the configurable product.\n\n To unassign a product variant from a configurable product, do one of the following:\n - Use [Delete Product API](#operation/deleteProducts) to delete the product variant.\n - 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.\n\n<h3>Bundle products</h3>\n\nA 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`.\nEach group can have multiple items, and shoppers can select items from each group to create a customized bundle.\n\nTo create a bundle product, you need the following:\n\n* <strong>Bundle product</strong>—[Define the parent product](#operation/createProducts) and include a [bundles](#operation/createProducts!path=bundles) array that\nspecifies the groups and items included in the bundle. Each group must define:\n * `group` - Name of the group (for example, \"tops\", \"bottoms\")\n * `required` - Whether a selection from this group is mandatory\n * `multiSelect` - Whether multiple items can be selected\n * `items` - List of products that can be selected from this group\n\n* <strong>Simple products</strong>—Define each simple product to include in the bundle. Each product must:\n * Include a [links](#operation/createProducts!path=links) array with a link of type `IN_BUNDLE` pointing to the bundle product\n * Be created separately using the [create product API](#operation/createProducts)\n\n<strong>Note:</strong> A simple product can be included only once in each bundle.\nIf the same item is specified in multiple groups, the API returns a `Duplicate SKU found in bundle items` error.\n\nTo update a bundle product, do one of the following:\n* Use the [Update products API](#operation/updateProducts) to modify the groups and items in the bundle\n* Use the [Delete products API](#operation/deleteProducts) to remove items from the bundle\n"
operationId: createProducts
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ContentEncoding'
responses:
'200':
$ref: '#/components/responses/AcceptedResponse'
'400':
$ref: '#/components/responses/InvalidItemsResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FeedProduct'
examples:
SimpleProductWithImages:
summary: Create a simple product
description: 'Create a simple product with required and optional fields.
'
value:
- sku: red-pants
source:
locale: en-US
name: red pants
slug: red-pants.html
status: ENABLED
description: long description about red pants
shortDescription: just pants
visibleIn:
- CATALOG
- SEARCH
metaTags:
title: 'Yoga pants '
description: Climb with Zeppelin Yoga Pant
keywords:
- pants
- yoga
attributes:
- code: cost
values:
- '10.5'
- code: states
values:
- TX
- CA
images:
- url: https://example.com/images/pants.jpg
label: photo of my pants!
roles:
- BASE
- THUMBNAIL
customRoles:
- widget
routes:
- path: men
- path: men/clothing/
position: 1
- path: men/clothing/pants
position: 1
ConfigurableProductWithVariants:
summary: Create a configurable product with four product variants
description: 'Create a configurable product `pants` with four product variants: `pants-red-32`, `pants-red-44`, `pants-green-32` and `pants-green-44`.
'
value:
- sku: pants
source:
locale: en-US
name: Yoga pants
slug: zeppelin-yoga-pant
status: ENABLED
visibleIn:
- CATALOG
configurations:
- attributeCode: color
label: Pants color
defaultVariantReferenceId: pants-color-red
type: SWATCH
values:
- variantReferenceId: pants-color-red
label: Red
colorHex: '#ff0000'
- variantReferenceId: pants-color-green
label: Green
imageUrl: https://www.example.com/media/catalog/product/green_main_1.jpg
- attributeCode: size
label: Pants size
defaultVariantReferenceId: pants-size-32
type: CONFIGURABLE
values:
- variantReferenceId: pants-size-32
label: '32'
- variantReferenceId: pants-size-44
label: '44'
- sku: pants-red-32
source:
locale: en-US
name: Zeppelin Yoga Pant Red 32 size
slug: pants-red-32
status: ENABLED
attributes:
- code: color
values:
- Red Pants
variantReferenceId: pants-color-red
- code: size
values:
- '32'
variantReferenceId: pants-size-32
links:
- type: variant_of
sku: pants
- sku: pants-red-44
source:
locale: en-US
name: Zeppelin Yoga Pant Red 44 size
slug: pants-red-44
status: ENABLED
attributes:
- code: color
values:
- Red Pants
variantReferenceId: pants-color-red
- code: size
values:
- '44'
variantReferenceId: pants-size-44
links:
- type: VARIANT_OF
sku: pants
- sku: pants-green-32
source:
locale: en-US
name: Zeppelin Yoga Pant Green 32 size
slug: pants-green-32
status: ENABLED
attributes:
- code: color
values:
- Green Pants
variantReferenceId: pants-color-green
- code: size
values:
- '32'
variantReferenceId: pants-size-32
links:
- type: VARIANT_OF
sku: pants
- sku: pants-green-44
source:
locale: en-US
name: Zeppelin Yoga Pant green 44 size
slug: pants-green-44
status: ENABLED
attributes:
- code: color
values:
- Green Pants
variantReferenceId: pants-color-green
- code: size
values:
- '44'
variantReferenceId: pants-size-44
links:
- type: VARIANT_OF
sku: pants
BundleProductWithItems:
summary: Create a bundle product with multiple items
description: 'Create a bundle product `bundle-outfit` with multiple items grouped into categories like `tops`, `bottoms`, and `accessories`. An item can be included only once in each bundle product.
'
value:
- sku: bundle-outfit
source:
locale: en-US
name: Bundle Outfit
slug: bundle-outfit
status: ENABLED
visibleIn:
- CATALOG
bundles:
- group: tops
required: true
multiSelect: false
defaultItemSkus:
- top-red
items:
- sku: top-red
qty: 1
userDefinedQty: false
- sku: top-blue
qty: 1
userDefinedQty: false
- group: bottoms
required: true
multiSelect: false
defaultItemSkus:
- bottom-black
items:
- sku: bottom-black
qty: 1
userDefinedQty: false
- sku: bottom-white
qty: 1
userDefinedQty: false
- group: accessories
required: false
multiSelect: true
items:
- sku: socks
qty: 1
userDefinedQty: true
- sku: headband
qty: 1
userDefinedQty: true
- sku: top-red
source:
locale: en-US
name: Red Top
slug: top-red
status: ENABLED
visibleIn:
- CATALOG
links:
- type: in_bundle
sku: bundle-outfit
- sku: top-blue
source:
locale: en-US
name: Blue Top
slug: top-blue
status: ENABLED
visibleIn:
- CATALOG
links:
- type: in_bundle
sku: bundle-outfit
- sku: bottom-black
source:
locale: en-US
name: Black Bottom
slug: bottom-black
status: ENABLED
visibleIn:
- CATALOG
links:
- type: in_bundle
sku: bundle-outfit
- sku: bottom-white
source:
locale: en-US
name: White Bottom
slug: bottom-white
status: ENABLED
visibleIn:
- CATALOG
links:
- type: in_bundle
sku: bundle-outfit
- sku: socks
source:
locale: en-US
name: Socks
slug: socks
status: ENABLED
visibleIn:
- CATALOG
links:
- type: in_bundle
sku: bundle-outfit
- sku: headband
source:
locale: en-US
name: Headband
slug: headband
status: ENABLED
visibleIn:
- CATALOG
links:
- type: in_bundle
sku: bundle-outfit
patch:
tags:
- Products
summary: Update products
description: 'Update products with specified `sku` and `source` values to replace existing field data with the data supplied in the request.
When the update is processed, the merge strategy is used to apply changes to `scalar` and `object` type fields.
For `array` type fields, a new value can be appended to the existing list. For an object list, you can update a specific object by matching on a key field. The following fields are supported:
* `attributes` - match on `code`
* `images` - match on `url`
* `routes` - match on `path`
* `links` - match on `type` and `sku`
* `bundles` match on `type` and `group`
* `configurations` match on `type` and `attributeCode`
* `externalIds` match on `type` and `origin`
> **Note:** Before submitting an update request, verify that the target entity exists using the [products](https://developer.adobe.com/commerce/services/includes/autogenerated/merchandising-api#products) GraphQL query. Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.
'
operationId: updateProducts
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ContentEncoding'
responses:
'200':
$ref: '#/components/responses/AcceptedResponse'
'400':
$ref: '#/components/responses/InvalidItemsResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FeedProductUpdate'
examples:
SimpleProductWithImages:
summary: Update a simple product
description: 'Update a simple product with the values provided in the request.
On update, changes to `scalar` and `object` type fields are applied using the merge strategy.
The replace strategy is used to apply changes for fields in an `array`.
In the example below, the following attributes are updated.
* `name` - Change the product name.
* `metaTags.title` - Change the title of the product detail page.
'
value:
- sku: red-pants
source:
locale: en-US
name: Red pants - discounts!
metaTags:
title: Updated - Red
UnassignProductVariant:
summary: Unassign product variant `pants-red-32` from configurable product `pants`
description: 'To unassign product variant `pants-red-32` from configurable product `pants` you need:
* remove the `variantReferenceId` from the `attributes` field
* remove the `links` association
'
value:
- sku: pants-red-32
source:
locale: en-US
attributes:
- code: color
values:
- Red Pants
variantReferenceId: null
- code: size
values:
- '32'
variantReferenceId: null
links: []
AddNewAccessoryItem:
summary: Add a new item `gloves` to the accessories group of the bundle product `bundle-outfit`
description: 'To add a new item `gloves` to the accessories group of the bundle product `bundle-outfit`, include the new item in the `items` array of the `accessories` group.
The previously created items `socks` and `headband` should be retained in the updated bundle.
Note that simple product `gloves` must be created separately using the create product API.
'
value:
- sku: bundle-outfit
source:
locale: en-US
bundles:
- group: accessories
required: false
multiSelect: true
items:
- sku: socks
qty: 1
userDefinedQty: true
- sku: headband
qty: 1
userDefinedQty: true
- sku: gloves
qty: 1
userDefinedQty: true
AddNewAttributeAndReplaceExisting:
summary: Add a new attribute and replace existing one
description: 'Add a new attribute `warehouse`, and update the value of the existing `cost` attribute for the simple product `red-pants`
In the example below:
* A new attribute with the code `warehouse` is added to the attributes list
* The value of the existing `cost` attribute is replaced with new value
The previously created `states` attribute is preserved.
Note: Don''t forget to create the product attribute metadata (<a href="#operation/createProductMetadata">link</a> for the `warehouse` attribute if it doesn''t exist yet.
'
value:
- sku: red-pants
source:
locale: en-US
attributes:
- code: warehouse
values:
- Austin
- code: cost
values:
- '12'
/v1/catalog/products/delete:
post:
tags:
- Products
summary: Delete products
description: 'Delete products with specified `sku` and `source` values
'
operationId: deleteProducts
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ContentEncoding'
responses:
'200':
$ref: '#/components/responses/AcceptedResponse'
'400':
$ref: '#/components/responses/InvalidItemsResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FeedProductDelete'
examples:
DeleteSimpleProduct:
summary: Delete product
description: 'Delete a simple product with specified `sku` and `source` values
'
value:
- sku: red-pants
source:
locale: en-US
components:
schemas:
FeedProductDelete:
title: Catalog Product delete payload
type: object
required:
- sku
- source
properties:
sku:
type: string
description: Product unique identifier
example: MH01
source:
$ref: '#/components/schemas/Source'
ProductExternalId:
title: External Ids
type: object
required:
- id
- origin
properties:
id:
type: string
description: External ID of the product.
origin:
type: string
description: External ID origin. Specifies the system that generated the external ID, such as Adobe Commerce, Google Product Ratings, etc.
ProductBundle:
title: Bundles
type: object
required:
- group
- items
properties:
group:
type: string
description: '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:
type: boolean
description: Indicates whether a shopper is required to select any products from this group to add the bundle to the shopping cart.
example: false
multiSelect:
type: boolean
description: Indicates whether multiple products can be selected by a shopper.
example: false
defaultItemSkus:
type: array
description: A list of default product SKUs that are selected in this bundle group.
items:
type: string
items:
type: array
description: '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.
'
items:
$ref: '#/components/schemas/ProductBundleItem'
FeedProductUpdate:
title: Catalog Product payload
type: object
required:
- sku
- source
properties:
sku:
type: string
description: SKU (Stock Keeping Unit) is a unique identifier for a product.
example: MH01
source:
$ref: '#/components/schemas/Source'
name:
type: string
description: Product name
example: Kangaroo Hoodie
slug:
type: string
description: The URL key for the product.
example: kangaroo-hoodie.html
description:
type:
- string
- 'null'
description: The main description for the product
example: A kangaroo hoodie for all seasons
shortDescription:
type:
- string
- 'null'
description: A short description of the product
example: A hoodie for all seasons with a kangaroo pocket
status:
type: string
description: 'Indicates whether the product is visible on the storefront.
The value is "Enabled" if it is visible, and "Disabled" if it is not visible.
'
example: ENABLED
enum:
- ENABLED
- DISABLED
visibleIn:
type: array
description: '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.
'
example:
- CATALOG
items:
enum:
- CATALOG
- SEARCH
metaTags:
$ref: '#/components/schemas/ProductMetaAttribute'
attributes:
type: array
description: A list of product attributes.
items:
$ref: '#/components/schemas/ProductAttribute'
images:
type: array
description: A list of product images.
items:
$ref: '#/components/schemas/ProductImage'
links:
type: array
description: 'A list of linked SKUs. For product variants, this is a required field that establishes a link between a product variant and the corresponding configurable product.
`VARIANT_OF` link type must be specified to establish a connection to the configurable product SKU.
'
items:
$ref: '#/components/schemas/ProductLink'
routes:
type: array
description: A list of product routes.
items:
$ref: '#/components/schemas/ProductRoutes'
configurations:
type: array
description: Composite products, such as configurable products, must provide a list of product options that a shopper can select (for example, "color", "size", etc.).
items:
$ref: '#/components/schemas/ProductConfiguration'
bundles:
type: array
description: 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").
items:
$ref: '#/components/schemas/ProductBundle'
externalIds:
type: array
description: A list of external IDs for the product.
items:
$ref: '#/components/schemas/ProductExternalId'
ProductAttribute:
title: Product Attribute
type: object
required:
- code
- values
properties:
code:
type: string
description: Product Attribute Code
values:
type: array
description: A list of value(s) associated with a specified attribute code.
items:
type: string
variantReferenceId:
type:
- string
- 'null'
description: '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.
'
ProductLink:
title: Links
required:
- type
- sku
type: object
properties:
type:
type: string
description: '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:
type: string
description: Product SKU
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-products-api-openapi.yml