Update item type configuration

put

https://api.bloomreach.com/api/cde/v1/workspaces/{workspace_id}/item-collections/{collection_name}/item-types/{item_type}/configurations/{configuration_id}

Updates the configuration for an item type with optimistic concurrency control.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Request requirements

Requires an If-Match header containing the current configuration hash.

Empty configuration

You may submit an explicitly empty configuration with no identifiers, attributes, or destinations.

Destination configuration

Each destination configuration includes three top-level properties: name, type, and target. The shape of target depends on the destination type.

Search target

Search destinations use the following target properties:

discovery_account_name
discovery_catalog_name
discovery_environment_name

Marketing target

Marketing destinations use a single target property:

engagement_project_id

Target validation

Destination target values must reference existing downstream resources that are valid for the current workspace.

Destination limits

The current implementation allows, per item type within a collection:

At most one Search destination
At most one Marketing destination

The schema remains open to future expansion beyond this limit.

Removing destinations

Removing destinations may require explicit destructive confirmation using force_delete=destinations.

Search destinations: Disconnects the collection from the Search target. This does not delete the Discovery catalog itself.
Marketing destinations: Deletes associated downstream resources.

Identifier mapping defaults

Policies are optional for identifier mappings. Any of the following applies the system default behavior:

Omitting the policies property
Sending an empty policies object
Explicitly setting on_failure.strategy to 'default'

Attribute mapping defaults

Data type requirements

Custom attributes: Require data_type.
System attributes: Inherit their effective types from the global meta configuration.

If data_type is submitted for a system attribute, it must match the inherited value, or the configuration update is rejected.

Policy defaults

Attribute policies and source-mapping policies can be omitted or sent as empty objects to apply the current system default behavior: 'skip_attribute'.

The deprecated strategy values 'default' and 'error' are treated the same as 'skip_attribute'.

Mapping types

Use 'jmes_path' for JMESPath extraction.
Use 'custom_expression' for custom expression mappings. Custom expressions use the Starlark language. For syntax and examples, see Write custom expressions.

category_paths builder mapping

The system attribute category_paths supports mapping_type: 'builder'. This uses the category builder to assemble CategoryPaths from either:

source_fields
level_fields

Path Params

workspace_id

uuid

required

length between 36 and 36

Unique identifier for the workspace

collection_name

string

required

length ≤ 128

Name of the collection

item_type

string

required

length between 1 and 64

Type of the item. Currently only 'product' is supported.

configuration_id

string

required

length ≤ 64

Configuration identifier to retrieve (latest alias or configuration etag)

Query Params

on_success_trigger

array of strings

length ≤ 10

Specifies actions to perform on successful completion of the operation. This parameter can be repeated to specify multiple triggers. These override any configured settings for the specific on success actions. For configuration updates, supported values include 'update-items' and 'update-destination-items'. For update-records jobs, supported values include 'update-items' and 'update-destination-items'. For update-items jobs, supported values include 'update-destination-items'. This is an open enumeration that may be extended with additional values.

on_success_trigger

force_delete

string

length ≤ 64

Explicitly confirms destructive cleanup that may be required by the requested update. Known value 'destinations' allows removal of destination links from the collection. For Discovery destinations, this disconnects the collection from the Discovery target and does not delete the Discovery catalog itself. For Engagement destinations, associated downstream resources such as Engagement catalogs will be deleted. This parameter is open for future extension. Even when force_delete=destinations is supplied, the request may still fail if the downstream resources are used by other systems and cannot be deleted safely.

Body Params

Complete item type configuration to update, including schema and destination settings

Writable configuration payload used when replacing collection configuration

schema

object

required

Schema configuration controlling how items are created and attributes are mapped

destinations

array of objects

required

length ≤ 1000

List of destination configurations. The current implementation allows at most one Discovery destination and one Engagement destination per collection, but the schema remains open to future destination expansion.

destinations*

Headers

If-Match

string

required

length ≤ 256

Current configuration hash (ETag) for optimistic concurrency control

Responses

Request requirements

Empty configuration

Destination configuration

Search target

Marketing target

Target validation

Destination limits

Removing destinations

Identifier mapping defaults

Attribute mapping defaults

Data type requirements

Policy defaults

Mapping types

category_paths builder mapping

200Successfully updated the item type configuration

401Standard error response format for normal application-level failures. In rare edge cases, such as malformed HTTP requests rejected before normal request handling completes, the API may return a more generic fallback error payload.

403Standard error response format for normal application-level failures. In rare edge cases, such as malformed HTTP requests rejected before normal request handling completes, the API may return a more generic fallback error payload.

404Standard error response format for normal application-level failures. In rare edge cases, such as malformed HTTP requests rejected before normal request handling completes, the API may return a more generic fallback error payload.

412Standard error response format for normal application-level failures. In rare edge cases, such as malformed HTTP requests rejected before normal request handling completes, the API may return a more generic fallback error payload.

428Standard error response format for normal application-level failures. In rare edge cases, such as malformed HTTP requests rejected before normal request handling completes, the API may return a more generic fallback error payload.

429Response format for rate limiting errors (429)

500Standard error response format for normal application-level failures. In rare edge cases, such as malformed HTTP requests rejected before normal request handling completes, the API may return a more generic fallback error payload.