Documentation Commerce Optimizer Connector

[PaaS only]{class="badge informative" title="Applies to Adobe Commerce on Cloud projects (Adobe-managed PaaS infrastructure) and on-premises projects only."}

Field mapping for connector feeds

Last update: October 8, 2026

CREATED FOR:

Intermediate
Admin
Developer

This page documents how the Adobe Commerce Optimizer Connector transforms Adobe Commerce catalog fields into the format required by the Commerce Optimizer Catalog Data Ingestion API. See the connector reference for the list of supported feeds and their API endpoints.

Products

The products feed sends data to the Products endpoint.

Adobe Commerce field

Commerce Optimizer API field

Mapping details

sku

storeViewCode

source/locale

name

urlKey

slug

productId

externalIds[0].id

Sets origin to "AdobeCommerce"

status

Converts the status to uppercase. Uses DISABLED if the status is missing or if a configurable or bundle product has no option values.

description

Uses an empty string if the description is missing.

shortDescription

Uses an empty string if the short description is missing.

visibility

visibleIn

Splits the comma-separated value and maps Catalog to CATALOG and Search to SEARCH. Drops other values.

metaTitle

metaTags/title

metaDescription

metaTags/description

metaKeyword

metaTags/keywords

Splits newline-separated keywords into an array and trims whitespace.

inStock, lowStock, weight, weightUnit

attributes[].code = "aco_ac_attributes"

Always adds an aco_ac_attributes entry as the first attribute. Its JSON value includes inStock and lowStock as strings. It includes weight and weightType when those values are available.

attributes[]

Maps each entry to its attribute code, string values, and matching variant reference ID when available. Skips inStock, lowStock, categories, weight, and weightType. The inventory-related values are included in aco_ac_attributes. Categories are exported as routes.

images[]

Skips images without a URL.
Exports url, label (empty if missing), and sortOrder (integer, defaults to 0).
Sorts images by sortOrder in ascending order.
Maps standard roles: image to BASE, small_image to SMALL, thumbnail to THUMBNAIL, and swatch_image to SWATCH. Exports other roles as customRoles[].

categoryData[].categoryPath

routes[].path

Skips entries with an empty category path.

categoryData[].productPosition

routes[].position

Uses 0 if the product position is missing.

links[].type + links[].sku

links[]

type uppercased; entries without sku dropped

parents[].productType + parents[].sku

links[]

Maps configurable to VARIANT_OF, and bundle or bundle_fixed to IN_BUNDLE. Converts other product types to uppercase. Skips parents without a SKU.

configurable options

configurations[]

Exports options that have an ID and at least one value.
Maps id to attributeCode. Sets type to SWATCH when swatchType is present, and to CONFIGURABLE otherwise.
Uses the ID of the default value as defaultVariantReferenceId.
Maps each value to variantReferenceId, label, colorHex, and imageUrl.

bundle options

bundles[]

Exports options that contain at least one item.
Uses the option label as group, or Bundle group if the label is empty. Copies required to the output.
Sets multiSelect to true for checkbox and multi render types.
Lists default SKUs in defaultItemSkus. Each item includes sku, qty (defaults to 0), and userDefinedQty (from qtyMutability, defaults to false).

Product attributes metadata

The productAttributes feed sends data to the Metadata endpoint.

Adobe Commerce field

Commerce Optimizer API field

Mapping details

attributeCode

code

storeViewCode

source/locale

label

dataType + frontendInput

dataType

See conversion table below

dataType and frontendInput

dataType

Uses the conversion rules below.

visible, visibleInSearch, visibleInListing, visibleInCompareList

visibleIn[]

When a flag is true, adds its corresponding value:
visible → PRODUCT_DETAIL
visibleInSearch → SEARCH_RESULTS
visibleInListing → PRODUCT_LISTING
visibleInCompareList → PRODUCT_COMPARE

filterable

sortable

searchable

searchWeight

searchTypes

Data type conversion

When dataType is int, the connector checks frontendInput. For other data types, frontendInput does not affect the conversion.

Input dataType

Input frontendInput

Output dataType

int

boolean

BOOLEAN

int

text or select

TEXT

int

Any other value, including a missing value

INTEGER

decimal

Not used

DECIMAL

text, varchar, static, datetime

Not used

TEXT

OBJECT

Not used

OBJECT

Any other value

Not used

TEXT

NOTE

When an attribute uses the OBJECT data type, the Products API attempts to parse its stored value as JSON. If parsing succeeds, the API returns the value as a nested object. Use OBJECT for structured attribute data that cannot be represented as a single value. For instructions, see Add product attributes dynamically.

Price books

The priceBooks feed sends data to the Price books endpoint.

Unlike the other connector feeds, the priceBooks feed is not collected by a SaaS Data Export indexer in Adobe Commerce. The connector generates this feed from the website and customer group configuration in the Admin.

For each website, the connector creates one base price book and one child price book for each customer group.

Use these formulas for priceBookId:

Base price books for regular prices: priceBookId = websiteCode.
Child price books for customer groups: priceBookId = websiteCode::sha1(customerGroupId), where sha1(customerGroupId) is the SHA-1 hex digest of the customer group’s integer ID.

The prices feed uses the same formula to assign each price entry to a price book. For information about how a storefront resolves priceBookId for a customer session, see Headless storefront integration.

Source field or value

Commerce Optimizer API field

Mapping details

websiteCode

parentId

Adds this field to child price books. Its value identifies the base price book.

Website name

name

Uses the website name for base price books. Uses Customer group name (Website name) for child price books.

websiteCode

parentId

Present only on child price books; points to the base price book

Website base currency

currency

Includes this field only on base price books. Child price books omit it.

Prices

The prices feed sends Adobe Commerce data to the Prices endpoint.

Feed input field

Commerce Optimizer API field

Mapping details

sku

Passes the SKU through unchanged.

websiteCode, customerGroupCode

priceBookId

Combines websiteCode with the SHA-1 hash of the customer group ID in customerGroupCode. If customerGroupCode is 0, uses websiteCode alone.

regular

Passes the regular price through unchanged.

discounts[]

If the source value is null, exports an empty array.
For entries with code set to special_price and a percentage, sets percentage to 100 - percentage when the value is between 0 and 100. Sets it to 0 at or outside that range.
Passes other entries, including price-based special prices, through unchanged.

tierPrices[]

Uses an empty array if the source value is missing or null.