API Reference

Catalog Data Ingestion API (1.0.0)

Download OpenAPI specification:Download

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:

Metadata—define and manage product attribute display on the storefront, define search characteristics, and so on
Products—define and manage items to include in a commerce catalog. Each product can have multiple attributes like name, description, SKU, images, etc.
Price books—define and manage unique scopes that can be used to manage product price discounts across customer tiers
Prices—define and manage the prices associated with product SKUs and assign the pricing scope where the price is used

Metadata

Product attribute metadata allows you to define how to display product attributes on the storefront, define search characteristics, and so on.

Create product attribute metadata.

Create or replace existing product attribute metadata resources.

To update existing product attribute metadata, use the update operation.

Request

path Parameters

DATA_SPACE_ID

required

string

The data space ID for the data space where commerce catalog data is stored. See SaaS configuration in Adobe Experience League.

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

code required	string Attribute code
required	object (Scope) Scope of the entity. For example it's locale "English"
visibleIn	Array of any Determines how the attribute is used on the storefront. `PRODUCT_DETAIL`: Product attribute is visible on the Product Detail Page. `PRODUCT_LISTING`: Product attribute is visible on Product Listing Page. `SEARCH_RESULTS`: Product attribute is visible on Search Results Page. `PRODUCT_COMPARE`: Product attribute is visible on Product Compare Page. Items Enum: "PRODUCT_DETAIL" "PRODUCT_LISTING" "SEARCH_RESULTS" "PRODUCT_COMPARE"
label required	string Label for the attribute that is displayed in user interfaces.
dataType required	string Data type Enum: "TEXT" "DECIMAL" "INTEGER" "BOOLEAN"
filterable	boolean Indicates whether the attribute can be used to filter products.
sortable	boolean Indicates whether the attribute can be used to sort products.
searchable	boolean Indicates whether the attribute value can be used in search queries to filter results.
searchWeight	number <float> The weight associated with a searchable attribute. Attributes with a greater weight are returned before attributes with a lower weight.
searchTypes	Array of strings Search types associated with this attribute, for example: `autocomplete`, `starts_with`, and so on. Items Enum: "AUTOCOMPLETE" "CONTAINS" "STARTS_WITH"

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the "message" and "errors" fields for details.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

post/v1/catalog/products/metadata/{DATA_SPACE_ID}

Request samples

Payload

application/json

Add product attribute information to a product.

[{"code": "name",
"scope": {"locale": "en"
},
"label": "Product Name",
"dataType": "TEXT",
"visibleIn": ["PRODUCT_DETAIL"
],
"filterable": false,
"sortable": false,
"searchable": true,
"searchWeight": 55,
"searchTypes": ["AUTOCOMPLETE"
]
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Update product attribute metadata.

Update existing product attribute metadata with new values. When the update is processed, the merge strategy is used to apply changes to scalar and object type fields. The replace strategy is used to apply changes for fields in an array.

Request

path Parameters

DATA_SPACE_ID

required

string

The data space ID for the data space where commerce catalog data is stored.

See SaaS configuration in Adobe Experience League.

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

code required	string Attribute code
required	object (Scope) Scope of the entity. For example it's locale "English"
visibleIn	Array of any Determines how the attribute is used on the storefront. `PRODUCT_DETAIL`: Product attribute is visible on the Product Detail Page. `PRODUCT_LISTING`: Product attribute is visible on Product Listing Page. `SEARCH_RESULTS`: Product attribute is visible on Search Results Page. `PRODUCT_COMPARE`: Product attribute is visible on Product Compare Page. Items Enum: "PRODUCT_DETAIL" "PRODUCT_LISTING" "SEARCH_RESULTS" "PRODUCT_COMPARE"
label	string Label for the attribute that is displayed in user interfaces.
dataType	string Data type Enum: "TEXT" "DECIMAL" "INTEGER" "BOOLEAN"
filterable	boolean Indicates whether the attribute can be used to filter products.
sortable	boolean Indicates whether the attribute can be used to sort products.
searchable	boolean Indicates whether the attribute value can be used in search queries to filter results.
searchWeight	number <float> The weight associated with a searchable attribute. Attributes with a greater weight are returned before attributes with a lower weight.
searchTypes	Array of strings Search types associated with this attribute, for example: `autocomplete`, `starts_with`, and so on. Items Enum: "AUTOCOMPLETE" "CONTAINS" "STARTS_WITH"

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

patch/v1/catalog/products/metadata/{DATA_SPACE_ID}

Request samples

Payload

application/json

Update existing product attribute metadata with new values. Note that fields with the array type will replace existing data. Example bellow updates the following attributes:

label - Change the product attribute label.
visibleIn - Add PRODUCT_LISTING role to the product attribute.

[{"code": "name",
"scope": {"locale": "en"
},
"label": "Updated - Product Name",
"visibleIn": ["PRODUCT_DETAIL",
"PRODUCT_LISTING"
]
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Delete product attributes metadata.

Remove product attribute metadata resources from the catalog data.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key.
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

code required	string Attribute code
required	object (Scope) Scope of the entity. For example it's locale "English"

Responses

200

All items in the request are accepted for further processing.

400

Some received items are invalid. Check the ‘invalidFeedItems’ node for specific errors.

403

Unauthorized request. Verify the ‘x-api-key’ and make sure that the JWT in ‘x-gw-signature’ is still valid.

post/v1/catalog/products/metadata/{DATA_SPACE_ID}/delete

Request samples

Payload

application/json

Marks existing product attribute metadata as deleted.

[{"code": "name",
"scope": {"locale": "en"
}
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Products

Product API to manage product data

Create products.

Simple Products

Create products or replace existing products with a specified `sku` and `scope`. If a product with the same data exists with the same SKU and scope, the product update request is ignored.

Use the update operation to modify values for an existing product.

Configurable Products

A configurable product is a product that offers multiple options, such as color and size. Each unique combination of these options, like 'color green' and 'size large,' defines a product variant. This variant is an independent product with its own SKU, price, and inventory. The configurable product acts as a container for these product variants.

To create a configurable product, you need the following:

Product attributes: Define the product attributes used to define a configurable product, such as "color", "size", etc.
Configurable product: Define the configurable product. Options is a required field. It defines the choices that a shopper can select.
Product variant: Define a product variant for a configurable product. "Attributes" with "variantReferenceId" and "links" of type VARIANT_OF must be defined for product variants.

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

To unassign a product variant from a configurable product, do one of the following:

Use Delete Product API to delete the product variant.
Use Update Product API to set the "variantReferenceId" to null and unassign the product variant from the configurable product by removing the "links" association.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID.

See SaaS data space provisioning in Adobe Experience League.

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

sku required	string SKU (Stock Keeping Unit) is a unique identifier for a product.
required	object (Scope) Scope of the entity. For example it's locale "English"
name required	string Product name
slug required	string The URL key for the product.
description	string The main description for the product
shortDescription	string A short description of the product
status required	string Indicates whether the product is visible on the storefront. The value is "Enabled" if it is visible, and "Disabled" if it is not visible. Enum: "ENABLED" "DISABLED"
visibleIn	Array of any 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. Items Enum: "CATALOG" "SEARCH"
metaTags	object Meta attributes that are specified in tags.
	Array of objects (Product Attribute) A list of product attributes.
	Array of objects (Product Image) A list of product images.
	Array of objects (Links) A list of linked SKUs.
	Array of objects (Routes) A list of product routes.
	Array of objects (ProductOption) Composite products, such as configurable products, must provide a list of product options that a shopper can select (for example, "color", "size", etc.).

Responses

200

All items accepted and will be processed asynchronously

400

One or all received items are invalid. Check the "invalidFeedItems" node for details

403

Unauthorized request. Verify the x-api-key value is correct and ensure the JWT is not expired in x-gw-signature.

post/v1/catalog/products/{DATA_SPACE_ID}

Request samples

Payload

application/json

Create a simple product with required and optional fields.

[{"sku": "red-pants",
"scope": {"locale": "en"
},
"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",
"type": "NUMBER",
"values": ["10.5"
]
},
{"code": "states",
"type": "ARRAY",
"values": ["TX",
"CA"
]
}
],
"images": [{"url": "https://example.com/images/pants.jpg",
"label": "photo of my pants!",
"roles": ["BASE",
"SMALL"
],
"customRoles": ["widget"
]
}
],
"routes": [{"path": "red-pants"
},
{"path": "pants/red-pants",
"position": 1
}
]
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Update products.

Update products with specified "sku" and "scope" 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. The replace strategy is used to apply changes for fields in an array.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID.

See SaaS data space provisioning in Adobe Experience League.

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

sku required	string SKU (Stock Keeping Unit) is a unique identifier for a product.
required	object (Scope) Scope of the entity. For example it's locale "English"
name	string Product name
slug	string The URL key for the product.
description	string The main description for the product
shortDescription	string A short description of the product
status	string Indicates whether the product is visible on the storefront. The value is "Enabled" if it is visible, and "Disabled" if it is not visible. Enum: "ENABLED" "DISABLED"
visibleIn	Array of any 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. Items Enum: "CATALOG" "SEARCH"
metaTags	object Meta attributes that are specified in tags.
	Array of objects (Product Attribute) A list of product attributes.
	Array of objects (Product Image) A list of product images.
	Array of objects (Links) 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.
	Array of objects (Routes) A list of product routes.
	Array of objects (ProductOption) Options associated with the product.

Responses

200

All items accepted and will be processed asynchronously

400

One or all received items are invalid. Check the "invalidFeedItems" node for details

403

Unauthorized request. Verify the x-api-key value is correct and ensure the JWT is not expired in x-gw-signature.

patch/v1/catalog/products/{DATA_SPACE_ID}

Request samples

Payload

application/json

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.
attributes - Add a new state, NM to the states attribute.

[{"sku": "red-pants",
"scope": {"locale": "en"
},
"name": "Red pants - discounts!",
"metaTags": {"title": "Updated - Red"
},
"attributes": [{"code": "cost",
"type": "NUMBER",
"values": ["10.5"
]
},
{"code": "states",
"type": "ARRAY",
"values": ["TX",
"CA",
"NM"
]
}
]
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Delete products.

Delete products with specified "sku" and "scope".

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID.

See SaaS data space provisioning in Adobe Experience League.

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

sku required	string Product unique identifier
required	object (Scope) Scope of the entity. For example it's locale "English"

Responses

200

All items accepted and will be processed asynchronously

400

One or all received items are invalid. Check the "invalidFeedItems" node for details

403

Unauthorized request. Verify the x-api-key value is correct and ensure the JWT is not expired in x-gw-signature.

post/v1/catalog/products/{DATA_SPACE_ID}/delete

Request samples

Payload

application/json

Delete a simple product with a specified sku and scope.

[{"sku": "red-pants",
"scope": {"locale": "en"
}
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Price Books

Price books define a unique scope that can be used to manage product price discounts across customer tiers. You can also specify the currency to use for product prices in the specified price book.

The catalog data model provides a default price book with id main and currency in US dollars (USD).

Create price books.

Create or replace existing price books.

Use the update operation to modify values for existing price books.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

priceBookId required	string Price book id
name	string Price book name
currency	string [ 1 .. 5 ] characters Price book currency

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

post/v1/catalog/price-books/{DATA_SPACE_ID}

Request samples

Payload

application/json

Create a price book and specify the currency for prices.

[{"priceBookId": "dealer-north",
"name": "Dealer North price book name",
"currency": "USD"
},
{"priceBookId": "VIP",
"currency": "USD"
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Update price books.

Update existing price books to change the name or the currency used for pricing. When the update is processed, the merge strategy is used to apply changes to scalar and object type fields. The replace strategy is used to apply changes for fields in an array.

To update the currency for the default price book, use the price book id main.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key.
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

priceBookId required	string Price book id
name	string Price book name
currency	string [ 1 .. 5 ] characters Price book currency

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the invalidFeedItems node for specific errors.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

patch/v1/catalog/price-books/{DATA_SPACE_ID}

Request samples

Payload

application/json

Update the "dealer-north" and default "main" price books to change the currency.

[{"priceBookId": "dealer-north",
"currency": "EUR"
},
{"priceBookId": "main",
"currency": "EUR"
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Delete price books.

Delete existing price books. Note that you cannot delete the default price book with id main.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key.
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

priceBookId required	string Price book id
name	string Price book name
currency	string [ 1 .. 5 ] characters Price book currency

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

post/v1/catalog/price-books/{DATA_SPACE_ID}/delete

Request samples

Payload

application/json

Delete the "dealer-north" price book.

[{"priceBookId": "dealer-north"
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Prices

Define prices for product SKUs. The scope identifies the price books and price tiers where the price is used. is used.

Create prices.

Simple Products

Create or replace existing product prices.

A price must be associated with at least the default price book with id main.

Configurable Products

Because configurable product price is calculated based on the price of the selected product variant, you don't need to send price data for configurable product skus. Sending price data for these skus can cause incorrect price calculations.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key
Content-Encoding	string Use this header if the payload is compressed with gzip Value: "gzip"

Request Body schema: application/json

Array

sku required	string Product SKU
priceBookId required	string Price book id
regular required	number <float> Regular price
	Array of Final Price (object) or Discount (object) Active discounts

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

post/v1/catalog/products/prices/{DATA_SPACE_ID}

Request samples

Payload

application/json

Add product price information to the catalog data.

[{"sku": "red-pants",
"priceBookId": "main",
"regular": 20
},
{"sku": "red-pants",
"priceBookId": "VIP",
"regular": 19.9,
"discounts": [{"code": "discount",
"percentage": 10
}
]
},
{"sku": "red-pants",
"priceBookId": "dealer-north",
"regular": 20.5,
"discounts": [{"code": "fixed",
"price": 18
}
]
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Update prices.

Change existing product prices. When the update is processed, the merge strategy is used to apply changes to scalar and object type fields. The replace strategy is used to apply changes for fields in an array.

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key.
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

sku required	string Product SKU
priceBookId required	string Price book id
regular	number <float> Regular price
	Array of Final Price (object) or Discount (object) Active discounts

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

patch/v1/catalog/products/prices/{DATA_SPACE_ID}

Request samples

Payload

application/json

Update existing product prices for the given SKU ("red-pants") and price book id ("dealer-north").

[{"sku": "red-pants",
"priceBookId": "dealer-north",
"discounts": [{"code": "discount",
"percentage": 30
}
]
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}

Delete prices.

Delete existing product prices

Request

path Parameters

DATA_SPACE_ID

required

string

Data Space ID

header Parameters

Content-Type required	string Value: "application/json"
x-api-key required	string Production public API key
x-gw-signature required	string JWT generated for Production public API key
Content-Encoding	string Use this header if the payload is compressed with gzip. Value: "gzip"

Request Body schema: application/json

Array

sku required	string Product SKU
priceBookId required	string Price book id

Responses

200

All items in the request are accepted for further processing.

400

Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.

403

Unauthorized request. Verify the x-api-key and make sure that the JWT in x-gw-signature is still valid.

post/v1/catalog/products/prices/{DATA_SPACE_ID}/delete

Request samples

Payload

application/json

Delete the existing product prices information

[{"sku": "red-pants",
"priceBookId": "dealer-north"
}
]

Response samples

application/json;charset=UTF-8

{"status": "ACCEPTED",
"acceptedCount": 4
}