Changelog
Stay up to date with Emporix API and service changes.
Category Tree - rebuild endpoint
rebuild endpointOverview
The Category Tree service now supports rebuilding a category tree for a given root category on demand. The rebuilt tree is returned in the response.
New endpoints
Triggers a rebuild of the category tree for the given root category and returns the result.
Known problems
There are no known problems.
AI Service - introduction of outputFormat field
outputFormat fieldOverview
Self-hosted LLM configuration now supports OAuth 2.0 client-credentials authentication through the new oAuthParams field on selfHostedParams. You can use it to obtain access tokens from your authorization server instead of providing a static authorization header. When oAuthParams is set, it is mutually exclusive with the static authorization header fields on SelfHostedParams.
The oAuthParams object includes:
url– base URL of the OAuth 2.0 authorization server; the access token is requested from{url}/tokenclientId– OAuth 2.0 client identifier registered with the authorization servergrantType– grant type used to obtain an access token; supported value isclient_credentialsscope– optional space-separated list of scopes to request for the access token
Updated endpoints
Response now includes the llmConfig.selfHostedParams.oAuthParams field.
Response now includes the llmConfig.selfHostedParams.oAuthParams field.
Response now includes the llmConfig.selfHostedParams.oAuthParams field.
Request now includes the llmConfig.selfHostedParams.oAuthParams field.
Request now includes the llmConfig.selfHostedParams.oAuthParams field.
Response now includes the llmConfig.selfHostedParams.oAuthParams field.
Response now includes the llmConfig.selfHostedParams.oAuthParams field.
Webhook Events - restriction on order.created and order.updated
restriction on order.created and order.updatedOverview
The order.created and order.updated webhook event payloads were extended with restriction.
Updated events
order.created
Event schema extended with restriction property.
order.updated
Event schema extended with restriction property.
Known problems
There are no known problems.
Links
AI Rag Indexer - support for ORDER type in /filter-metadata and /rag-metadata endpoints
ORDER type in /filter-metadata and /rag-metadata endpointsOverview
The endpoints /filter-metadata and /rag-metadata of AI Rag Indexer have been enhanced to support ORDER type.
Updated endpoints
Support for ORDER type.
Support for ORDER type.
Known problems
There are no known problems.
Indexing Service - mixin path allowlist for BatteryIncluded
Overview
The IndexConfiguration object has been extended with a new optional includedMixinPaths property for the BATTERY_INCLUDED provider. It is a glob-based allowlist of product mixin paths (matched against full dot-notation paths rooted at the mixin key), where * matches within a single path segment and ** matches across one or more segments. When includedMixinPaths is non-empty, only matching mixin paths are indexed, and it must not be combined with excludedMixinKeys. Malformed glob patterns are rejected with a validation error.
Updated endpoints
Property includedMixinPaths can be provided for the BATTERY_INCLUDED provider.
Property includedMixinPaths is returned.
Property includedMixinPaths is returned.
Property includedMixinPaths can be updated.
Known problems
There are no known problems.
Schema Service - bulk patching of custom instances
Overview
The Schema Service now supports partially updating multiple custom instances in a single request. Each item provides the custom instance id and a list of patch operations to apply. The maximum batch size is 200, and each item returns its own result status.
New endpoints
Partially updates up to 200 custom instances in one request by applying patch operations to each item.
Known problems
There are no known problems.
Quote Service - customerReference and customerComment properties
Overview
The Quote object has been extended with two new properties that allow customers to provide additional information on their quotes:
customerReference- A customer-provided reference stored on the quote (e.g., a purchase order number like "PO-12345")customerComment- A customer-provided comment stored on the quote (e.g., "Please deliver before Friday")
These properties can be set when creating a quote, creating a quote from a cart, or when updating a quote.
Updated endpoints
Properties customerReference and customerComment can be provided.
Properties customerReference and customerComment can be provided.
Properties customerReference and customerComment are returned.
Properties customerReference and customerComment are returned.
Properties customerReference and customerComment can be updated. Customers can update these on own quotes.
Known problems
There are no known problems.
AI Service - streaming chat responses
Overview
AI Service now supports streaming LLM responses for endpoint-triggered agents through a new Server-Sent Events endpoint. This lets clients receive incremental output over text/event-stream.
New endpoints
Adds POST /ai-service/{tenant}/agentic/chat-stream for streaming chat responses over text/event-stream.
Known problems
There are no known problems.
Schema and IAM Services - digits now supported in custom entity and scope IDs
Overview
Custom entity IDs in the Schema Service and scope IDs in the IAM Service now accept digits alongside letters and other allowed characters, giving more flexibility when naming custom types and scopes.
Updated endpoints
The id field now accepts digits.
The id field now accepts digits.
The scopeId path parameter now accepts digits.
Known problems
There are no known problems.
AI Service - introduction of 'outputFormat' field
Overview
The AI Service API now accepts a JSON Schema (as a JSON string) in the outputFormat field to constrain the structure of the agent response. This enables clients to request predictable, machine-readable output for easier integration with downstream workflows.
Updated endpoints
Response now includes the outputFormat field.
Response now includes the outputFormat field.
Response now includes the outputFormat field.
Request now includes the outputFormat field.
Request now includes the outputFormat field.
Response now includes the outputFormat field.
Response now includes the outputFormat field.
Country Service - X-Version header no longer required
Overview
The X-Version header is no longer required for Country Service endpoints.
Updated endpoints
The X-Version header is no longer required.
The X-Version header is no longer required.
The X-Version header is no longer required.
The X-Version header is no longer required.
The X-Version header is no longer required.
Known problems
There are no known problems.
Media, Schema, and Product Services - mixin support for media assets
Overview
Media assets now support mixins, consistent with other Emporix entities. The Schema Service supports a new MEDIA schema type for defining mixin schemas, but custom attribute values must still be provided in the asset payload through mixins and metadata.mixins when creating or updating assets through the Media Service. Category and Product Service endpoints do not accept media in requests; when media is created and linked to a category or product, the media items in responses include the corresponding mixin values.
Updated endpoints
Request accepts mixins and metadata.mixins.
Request accepts mixins and metadata.mixins.
Response includes mixins and metadata.mixins.
Response includes mixins and metadata.mixins.
MEDIA added to supported schema types.
MEDIA added to supported schema types.
Response media items include a mixins field.
Response media items include a mixins field.
Response media items include a mixins field.
Response media items include a mixins field.
Response media items include a mixins field.
Known problems
There are no known problems.
AI Rag Indexer Service - deprecated endpoint
Overview
The AI Rag Indexer Service endpoint for reindexing has been marked as deprecated and will be removed on 2026-12-01. Instead, use the Creating reindex job endpoint.
Deprecated endpoints
Use the Creating reindex job endpoint instead.
Known problems
There are no known problems.
Indexing Service - deprecated endpoint
Overview
The Indexing Service endpoint for reindexing has been marked as deprecated and will be removed on 2026-12-01. Use the Creating reindex job endpoint instead.
Deprecated endpoints
Use the Creating reindex job endpoint instead.
Known problems
There are no known problems.
Indexing Service - Reindex Jobs
Overview
The Indexing Service was extended with new endpoints for creating and fetching reindex jobs. For now, reindexing supports PRODUCT and custom schema entity types.
New endpoints
Endpoint for creating reindex job.
Endpoint for fetching reindex jobs.
Endpoint for fetching reindex job.
AI Service - commerce event trigger filter support and job status update
Overview
The AI Service API now supports payload-level filtering for commerce_events agent triggers. You can define filter expressions so an agent is triggered only when an incoming commerce event payload matches the configured criteria. Additionally, jobs now support the skipped status value.
Updated types
AgentTrigger
Added optional filter field for the commerce_events trigger variant.
JobStatus
Added skipped enum value.
Updated endpoints
Response can now include trigger.filter for commerce_events triggers.
Response can now include trigger.filter for commerce_events triggers.
Request payload now supports trigger.filter for commerce_events triggers.
Request payload now supports trigger.filter for commerce_events triggers.
Job responses can now return status: skipped.
Job responses can now return status: skipped.
Job response can now return status: skipped.
Category Service - X-Version header no longer required
X-Version header no longer requiredOverview
The Category Service no longer requires the X-Version header to be passed in requests. Existing integrations that still send the X-Version header will continue to work without any changes.
Affected endpoints
All Category Service endpoints are affected. The X-Version request header is no longer required and can be safely omitted.
The X-Version request header is no longer required and is ignored when provided.
Known problems
There are no known problems.
Webhook Events - cartId and quoteId on order.created and order.updated
cartId and quoteId on order.created and order.updatedOverview
The order.created and order.updated webhook event payloads were extended with cartId and quoteId. These fields link an order to its source cart or quote and are populated when the order was created from checkout.
cartId— identifier of the cart used to create the order (cart checkout).quoteId— identifier of the quote from which the order was created (quote checkout).
Either field may be omitted when it does not apply to the order.
Updated events
order.created
Event schema extended with optional cartId and quoteId properties.
order.updated
Event schema extended with optional cartId and quoteId properties.
Known problems
There are no known problems.
Links
Approval Service - legal entity scoping and approval response fields
Overview
The Approval Service now scopes approvals to the B2B legal entity from the customer token. Previously, customers could see approvals created for other companies because the Legal-Entity-Id has not been stored on the Approval model.
New and updated approvals store legalEntity on the document and are filtered by legalEntity.id. GET responses also expose createdResource when a downstream resource (for checkout, typically an order) exists after the approval flow completes.
Behavior change (not backward compatible)
When the Legal-Entity-Id request header is sent (injected for B2B customer tokens — see B2B token and legal entity), the service:
Creates approvals for that legal entity only (requestor and approver contact assignments are resolved for the given entity).
Returns only approvals whose stored
legalEntity.idmatches thelegal-entity-idfrom token.
Existing approvals created before this release do not have legalEntity stored. They are not returned when Legal-Entity-Id is present in token, because they cannot match the legal-entity filter. This is intentional and not backward compatible: tenants will not see historical approvals through the scoped B2B API.
Updated endpoints
Respects Legal-Entity-Id; persists legalEntity on the approval.
Filtered by Legal-Entity-Id when present; response includes legalEntity and optional createdResource.
Filtered by Legal-Entity-Id when present; response includes legalEntity and optional createdResource.
Filtered by Legal-Entity-Id when present.
Filtered by Legal-Entity-Id when present.
Respects Legal-Entity-Id when checking existing approvals.
Respects Legal-Entity-Id for contact assignment and approver resolution.
Schema updates
The getApprovalResponse schema was extended with:
legalEntity— object withid(legal entity identifier); set when the approval is createdcreatedResource— object withid(identifier of the created resource; for checkout, typically an order ID); omitted until the approved action produces a linked resource
Known problems
There are no known problems.
Emporix SDK - Batch cart item update and removal of X-Version header from category clients
Overview
A new version 1.3.1 of the Emporix SDK has been released with the following changes:
support for batch updating cart items via
PUT /cart/{tenant}/carts/{cartId}/itemsBatchremoval of the
X-Versionheader from Category Service clients (CategoryClient,CategoryAssignmentClient,CategoryTreeClient)
New methods
CartItemsClient.updateMultipleItemsToCart
Updates multiple cart items in a single batch operation (maximum 50 items). Returns HTTP 207 (Multi-Status) with per-item outcomes aligned to request order.
New types
UpdateCartItemsBatchRequest
Batch cart item update request. Each entry must include a cart item id.
UpdateCartItemsBatchEntryResponse
Per-item outcome for a batch update (index, id, code, status, message, details).
Updated types
BatchItemResponse
Added index field matching the position of the item in the request body.
Updated clients
CategoryClient
No longer sends the X-Version header on requests.
CategoryAssignmentClient
No longer sends the X-Version header on requests.
CategoryTreeClient
No longer sends the X-Version header on requests.
Known problems
There are no known problems.
AI Service - Support for file upload
Overview
The AI Service has been enhanced with a new endpoint that allows you to upload a file and attach it to the agent. Then, when calling chat endpoints it is possible to reference this file.
New endpoints
Attaches a file to the agent
Updated endpoints
Request body extended with attachments field.
Request body extended with attachments field.
Known problems
There are no known problems.
AI Service - LLM models from supported providers
Overview
The AI Service has been enhanced with a new endpoint that lists available LLM models from supported LLM providers: OpenAI, Anthropic, and Google.
The service retrieves models directly from each provider's models API.
Each model entry includes an identifier, display name, optional description, and a thinking flag indicating whether the model supports thinking capabilities.
New endpoints
Returns models grouped by provider (openai, anthropic, google). Requires ai.agent_read.
Known problems
There are no known problems.
Indexing Service - Battery Included provider support
Overview
The Indexing Service now supports Battery Included as a new index provider alongside Algolia. Only one provider can be active per tenant at a time. Battery Included only supports the MERGE site-aware fields strategy; tenants configured with the SPLIT strategy will have Battery Included indexing silently skipped.
This feature is in a preview state and payload sent to battery included is subject to change.
Updated endpoints
Added BATTERY_INCLUDED provider support with new excludedMixinKeys field. Only one provider can be active per tenant at a time.
Response may include Battery Included configurations with excludedMixinKeys.
provider path parameter now accepts BATTERY_INCLUDED.
Supports updating Battery Included configurations with excludedMixinKeys.
Response may include Battery Included public configurations.
provider path parameter now accepts BATTERY_INCLUDED.
Known problems
There are no known problems.
Availability Service - deprecated endpoints
Overview
The Availability Service endpoints for managing availabilities that accept site as a query parameter, which were marked as deprecated on 2025-01-13, will be removed on 2026-09-01. They have been replaced with new endpoints that accept site as a path parameter.
The Availability Service endpoints for managing locations have been marked as deprecated and will be removed on 2026-09-01 due to the planned sunset of the related functionalities.
Deprecated endpoints
Availability endpoints accepting site as query parameter
[GET] /{tenant}/availability/{productId}?site
Deprecated. Use Retrieving a product availability instead.
[POST] /{tenant}/availability/{productId}?site
Deprecated. Use Creating a new availability for a product instead.
[PUT] /{tenant}/availability/{productId}?site
Deprecated. Use Upserting availability information of a product instead.
[DELETE] /{tenant}/availability/{productId}?site
Deprecated. Use Deleting availability information of a product instead.
[GET] /{tenant}/availability?site
Deprecated. Use Retrieving all availability information for a site instead.
[POST] /{tenant}/availability?site
Deprecated. Use Retrieving product availabilities instead.
Deprecated due to planned sunset of related functionalities.
Deprecated due to planned sunset of related functionalities.
Deprecated due to planned sunset of related functionalities.
Deprecated due to planned sunset of related functionalities.
Deprecated due to planned sunset of related functionalities.
Known problems
There are no known problems.
Schema Service — explicit owner on custom instance creation
owner on custom instance creationOverview
The Schema Service now accepts an optional owner field in the request body when creating a custom instance, so clients can assign ownership explicitly instead of relying on the platform to derive it from the calling principal.
The owner field can be set explicitly only by clients authorized with a manage scope (schema.custominstance_manage or custom.{lowerCaseType}_manage). When the request is authorized with a manage_own scope, the field is ignored and ownership is set automatically to the user who created the custom instance. When a manage scope is granted but the field is omitted, ownership is likewise set automatically to the user who created the custom instance.
The following limitations apply when providing owner:
typecan only be set toCUSTOMERorEMPLOYEE. TheSERVICEtype cannot be assigned explicitly.legalEntityIdcan be provided only whentypeisCUSTOMER.The
ownerfield is immutable. It can only be set during creation.
Updated endpoints
The request body now accepts an optional owner.
The request body now accepts an optional owner field.
Known problems
There are no known problems.
AI Service - RAG_EMPORIX support for custom entity types
Overview
The tool of RAG_EMPORIX type allow specifying the custom entity type by using entityType field.
Updated endpoints
Field entityType of RAG_EMPORIX tool type supports custom entity types.
Field entityType of RAG_EMPORIX tool type supports custom entity types.
Field entityType of RAG_EMPORIX tool type supports custom entity types.
Field entityType of RAG_EMPORIX tool type supports custom entity types.
Field entityType of RAG_EMPORIX tool type supports custom entity types.
Known problems
There are no known problems.
Webhook Events - updated schema.custom-instance-updated and schema.custom-instance-created events schema
schema.custom-instance-updated and schema.custom-instance-created events schemaOverview
The schema.custom-instance-updated and schema.custom-instance-created webhook events documentation has been updated to reflect the current payload structure.
Updated event
schema.custom-instance-updated
Updated event schema by including nested media and owner data.
schema.custom-instance-created
Updated event schema by including nested media and owner data.
Known problems
There are no known problems.
Links
Approval Service - quote approval process
Overview
The Approval Service supports quote checkout approvals alongside cart approvals. For resourceType: QUOTE, the client sends the quote ID in resourceId and does not send details. The service loads quote line and price data from the quote integration. For resourceType: CART, details remains required as before.
Updated endpoints
Supports resourceType: QUOTE with quote resourceId.
Response resource payloads align with updated item and price schemas.
Response resource payloads align with updated item and price schemas.
Request may use resourceType: QUOTE and a quote resourceId.
Request may use resourceType: QUOTE and a quote resourceId.
Schema updates
The Approval Service API reference schemas were extended with:
resourceTypevalueQUOTEresourceItem:itemId;itemPriceas line-level price (unitPrice,newUnitPrice,calculatedPrice)price(totals):netValue,grossValue,taxValue
Known problems
There are no known problems.
Approval Service - deprecated fields
Overview
All deprecations will be removed on 2026-11-30. Several fields in the approval response have been deprecated in favor of new, more descriptive fields. The new fields provide a more comprehensive and consistent way to access price calculations.
Deprecated approval resource level fields:
totalPrice.amount- usetotalPrice.netValue,totalPrice.grossValueandtotalPrice.taxValueinsteadsubTotalPrice.amount- usesubTotalPrice.netValue,subTotalPrice.grossValueandsubTotalPrice.taxValueinstead
Deprecated approval resource-item level fields:
itemYrn- useitemIdinsteaditemPrice.amount- usecalculatedPriceandunitPriceinstead
Updated endpoints
Deprecated response fields in favor of new more comprehensive way to represent prices.
Deprecated response fields in favor of new more comprehensive way to represent prices.
Known problems
There are no known problems.
AI Rag Indexer - support for custom entity types in /filter-metadata and /rag-metadata endpoints
/filter-metadata and /rag-metadata endpointsOverview
The endpoints /filter-metadata and /rag-metadata of AI Rag Indexer have been enhanced to support custom entity types.
Updated endpoints
Support for custom entity types.
Support for custom entity types.
Known problems
There are no known problems.
AI Rag Indexer - name and description fields from /filter-metadata endpoint deprecated
name and description fields from /filter-metadata endpoint deprecatedOverview
The fields name and description from the response of /filter-metadata endpoint of AI Rag Indexer have been deprecated. These fields were previously used to provide additional information about the filters, but they are no longer necessary for the functionality of the service. They will be removed on 2026-12-01.
Affected endpoint
Fields name and description from the response are marked as deprecated.
Known problems
There are no known problems.
AI Service - RAG_EMPORIX filter fields
Overview
The tool of RAG_EMPORIX type has been enhanced with a filterFields field, which allows specifying which fields are available for filtering in the vector index.
Updated endpoints
Response enhanced with filterFields field.
Response enhanced with filterFields field.
Response enhanced with filterFields field.
Request body enhanced with filterFields field.
Request body enhanced with filterFields field.
Known problems
There are no known problems.
SEPA Export Service - deprecation
Overview
The SEPA Export Service has been deprecated and will be removed on 2026-08-24.
Known problems
There are no known problems.
Overview
The SEPA Export Service is now deprecated in its entirety. All endpoints exposed by the service are deprecated and the service is scheduled to be officially removed on 2026-08-24.
The SEPA Export Service and all of its endpoints are no longer maintained and will be officially removed on 2026-08-24. Make sure to migrate any integrations that still rely on the service before that date.
Deprecated endpoints
All endpoints under the /sepa-export/{tenant}/ base path are deprecated. For the full list of affected endpoints, refer to the SEPA Export Service API Reference.
Known problems
There are no known problems.
Pick-pack Service - service deprecation
Overview
The Pick-pack Service is now deprecated in its entirety. All endpoints exposed by the service are deprecated and the service is scheduled to be officially removed on 2026-08-24.
The Pick-pack Service and all of its endpoints are no longer maintained and will be officially removed on 2026-08-24. Make sure to migrate any integrations that still rely on the service before that date.
Deprecated endpoints
All endpoints under the /pick-pack/{tenant} base path are deprecated, including those used to manage pick-pack orders, order cycles, assignees, recalculations, and events. For the full list of affected endpoints, refer to the Pick-pack Service API Reference.
Known problems
There are no known problems.
Price Service - siteCodes support in price search
Overview
The Price Service search endpoint now supports a new siteCodes field, which allows searching for prices across multiple site codes in a single request. If the existing siteCode field is specified, siteCodes is ignored.
Updated endpoints
New attribute siteCodes added to request payload. Accepts an array of site codes for which the prices should be retrieved.
Known problems
There are no known problems.
Emporix SDK - Dynamic variants support and recalculation jobs
Overview
A new version 1.3.0 of the Emporix SDK adds support for DYNAMIC_VARIANT products and introduces a dedicated client for asynchronous dynamic variant recalculation jobs.
Dynamic variants form a flexible hierarchy (up to 4 levels). Each variant stores its own distinguishing attributes (ownVariantAttributes) and a root dynamic variant contains a denormalized variants map of all descendants. For bulk imports, the variant tree can be rebuilt asynchronously using the recalculation job endpoints.
New client
RecalculationJobClient
Declarative HTTP client for Product Service dynamic variant recalculation jobs. Automatically registered as a Spring bean.
New methods
RecalculationJobClient.triggerDynamicVariantRecalculation
Triggers asynchronous recalculation jobs for one or more dynamic variants.
RecalculationJobClient.listDynamicVariantRecalculationJobs
Lists recalculation jobs, optionally filtered by status.
RecalculationJobClient.getDynamicVariantRecalculationJob
Retrieves a single recalculation job by ID.
New types
Dynamic variant recalculation
DynamicVariantRecalculationRequest
Request body for triggering recalculation. Contains up to 1000 productIds.
DynamicVariantRecalculationResponse
Response containing jobs and skippedProductIds.
DynamicVariantRecalculationJobResponse
Represents a single recalculation job (id, root, status, timestamps, error).
DynamicVariantRecalculationJobStatus
Job status enum: PENDING, PROCESSING, FINISHED, FAILED, FAILED_PERMANENT.
Dynamic variant attributes and variant map
DynamicVariantAttribute
Attribute entry with localized name and typed value.
DynamicVariantAttributeValue
Typed value containing type, qualifier, optional unit, and localized display name.
DynamicVariantAttributeType
Attribute value type enum (e.g. STRING, BOOLEAN, NUMBER, DECIMAL).
VariantAttributeQualifier
Qualifier value with custom serializer/deserializer for stable JSON representation.
VariantMapEntry
Entry stored in a root product’s variants map with accumulated attributes for a descendant.
DynamicVariantInfo
Metadata information for dynamic variant trees (for example, missing ancestor, cycle detection).
Requests for DYNAMIC_VARIANT products
DynamicVariantCreateRequest
Create request for DYNAMIC_VARIANT products, including ownVariantAttributes.
DynamicVariantUpdateRequest
Update request for DYNAMIC_VARIANT products, including ownVariantAttributes.
Product presentation - brand & labels
Brand
Brand representation embedded in ProductResponse (resolved when expanded by the API).
Label
Label representation embedded in ProductResponse (resolved when expanded by the API).
Updated types
ProductResponse
Added dynamic variant support (dynamicVariantType, parentVariantId, parentVariantPath, sellable, ownVariantAttributes, inheritedVariantAttributes, root variants map) and presentation fields (labelIds, labels, brandId, brand).
ProductMetadataResponse
Added dynamicVariantInfo for dynamic-variant tree diagnostics.
GenericProductCreateRequest
Added dynamic variant fields (productType, parentVariantId, dynamicVariantType, sellable, ownVariantAttributes).
GenericProductUpdateRequest
Added dynamic variant fields (sellable, dynamicVariantType, parentVariantId, ownVariantAttributes).
ProductPartialUpdateRequest
Added dynamic variant fields (dynamicVariantType, sellable, ownVariantAttributes) and additional partial-update fields (labelIds, brandId).
Known problems
Constructor signature changes (compile-time breaking for some usages)
The all-args constructors generated by Lombok changed due to newly added fields in:
ProductResponseGenericProductCreateRequestGenericProductUpdateRequestProductPartialUpdateRequest
If your code instantiates these classes using constructors, you may hit compilation errors after upgrading.
Recommended fix: use the Lombok builder (.builder()...build()) instead of constructors.
Class GenericProductUpdateRequest is now using MetadataRequest instead of VariantProductMetadataRequest for the metadata field.
The following classes were updated to contain productType field that is necessary for upserting and creating products:
BundledProductCreateRequestDynamicVariantCreateRequestParentVariantCreateRequestProductVariantCreateRequestBundledProductUpdateRequestParentVariantUpdateRequestProductVariantUpdateRequest
IAM Service - access control restrictions, predefined scopes, and deprecations
Overview
The IAM Service has been extended in three main areas, and the legacy roles/permissions/resources object model is being phased out.
Access control assignment restrictions
Access controls now expose a restrictedTo property that limits the type of group an access control can be assigned to:
CUSTOMER- the access control can be assigned only to groups ofCUSTOMERuser type.EMPLOYEE- the access control can be assigned only to groups ofEMPLOYEEuser type.
If restrictedTo is not present on an access control, it can be assigned to any group regardless of its user type.
Multiple domains per access control
The domain property on access controls has been replaced with domains - a list of domain identifiers.
Predefined scopes
The endpoints for listing and retrieving scopes now also return predefined scopes and scopes responses now include a read-only predefined flag indicating whether a scope is system-defined or user-created. Moreover, predefined scopes can now be referenced when creating or updating access controls.
Deprecation of the roles, permissions, and resources model
The legacy roles, permissions, and resources object model is being phased out. The endpoints that retrieve these objects, as well as the roleId and resourceId properties on access controls and the expand, roleId, and resourceId query parameters that resolved them, are now deprecated. The endpoints for retrieving user access controls and user permissions for a specific resource - which are also tied to the legacy model - are deprecated as well.
The deprecated endpoints, properties, and query parameters listed above are no longer maintained and will be removed on October 1, 2026. Make sure to migrate any integrations that still rely on them before that date.
Updated endpoints
Property restrictedTo introduced. Property domain replaced with domains. Response properties roleId and resourceId are now deprecated. Query parameters expand, roleId, and resourceId are now deprecated.
Property restrictedTo introduced. Property domain replaced with domains. Response properties roleId and resourceId are now deprecated. Query parameter expand is now deprecated.
Property restrictedTo introduced. Property domain replaced with domains. Predefined scopes can now be used when creating or updating access controls.
Property restrictedTo introduced. Property domain replaced with domains. Response properties roleId and resourceId are now deprecated. Query parameter expand is now deprecated.
Property restrictedTo introduced. Property domain replaced with domains. Response properties roleId and resourceId are now deprecated. Query parameter expand is now deprecated.
Property restrictedTo introduced. Property domain replaced with domains. Response properties roleId and resourceId are now deprecated. Query parameter expand is now deprecated.
Response now includes the read-only predefined flag. The endpoint now also returns predefined access control scopes in addition to user-created custom scopes.
Response now includes the read-only predefined flag. The endpoint now also returns predefined access control scopes in addition to user-created custom scopes.
Deprecated endpoints
Endpoint deprecated.
Endpoint deprecated.
Endpoint deprecated.
Endpoint deprecated.
Endpoint deprecated.
Endpoint deprecated.
Endpoint deprecated.
Endpoint deprecated.
Known problems
There are no known problems.
Product Service - code on dynamic variant variants map entries
Overview
For DYNAMIC_VARIANT root products, each entry in the denormalized variants map now includes code: the business code of the corresponding variant product (the same value as on the variant product itself). This lets storefronts and integrations read SKU-style identifiers from the root response without an extra lookup.
Webhook event documentation for payloads that include the dynamic variant variants structure has been aligned with this field.
Modified behavior
When you retrieve a dynamic variant root product, every key under variants includes:
code— string, code of the source variant product
Existing fields such as version, name, parentVariantId, sellable, dynamicVariantType, and variantAttributes are unchanged.
Known problems
There are no known problems.
Links
Product Service - expand brand and labels in product responses
Overview
Product responses can now be enriched with expanded brand and label data using the expand query parameter.
Modified behavior
When requesting product data, you can now use:
expand=brandto include abrandobject expanded frombrandIdexpand=labelsto include alabelsarray expanded fromlabelIdsmultiple values can be combined, for example:
expand=template,parentVariant,brand,labels
Schema updates
The product response schemas were extended with:
brand(expanded object)labels(expanded array)
Known problems
There are no known problems.
Webhook Events - updated index-item.updated event schema
index-item.updated event schemaOverview
The index-item.updated webhook event documentation has been updated to reflect the current payload structure used by staging changes.
Updated event
index-item.updated
Updated event schema for index item update payload, including nested product, variant, site-specific price, and availability data.
Known problems
There are no known problems.
Links
Cart Service - batch update endpoint for cart items
Overview
The Cart Service API reference now documents a new batch update endpoint for cart items. You can update multiple items in a cart in a single request using PUT /cart/{tenant}/carts/{cartId}/itemsBatch. The response for POST /cart/{tenant}/carts/{cartId}/itemsBatch was extended with the index property in each batch entry.
New endpoints
New endpoint for updating multiple cart items in one request. The number of cart items that can be edited in one request is limited to 50.
Updated endpoints
Response for POST /cart/{tenant}/carts/{cartId}/itemsBatch was extended with the index property for each batch entry.
Known problems
There are no known problems.
Schema Service - Export and Import functionality for custom schema types
Overview
The Schema Service has been extended with endpoints for exporting and importing custom schema types.
Updated endpoints
New endpoint for exporting custom entities.
New endpoint for importing custom entities.
Known problems
There are no known problems.
Emporix SDK - Availability Service Q-param support, total count header and search improvements
Overview
A new 1.2.5 version of the Emporix SDK has been released with the following changes:
support for the
X-Total-Countresponse header on availability search endpointssupport for the standard
qquery parameter on the site-specific availability endpointsupport for the
qrequest body attribute on the availability search endpointsupport for the standard
sortparameter on both availability retrieval and search endpoints
Updated methods
AvailabilityClient.getAvailabilitiesForSite
The response now includes the X-Total-Count header. Added support for the standard q query parameter and sort parameter.
AvailabilityClient.searchAvailability
The response now includes the X-Total-Count header. Added support for the standard q request body attribute as an alternative filtering method and sort parameter.
New types
SearchDto
Request body for the availability search endpoint. Accepts either a set of productIds for filtering by specific products, or a q string for query-based filtering. The two fields are mutually exclusive.
Known problems
There are no known problems.
Emporix SDK - Multi-tenant support
Overview
A new 1.2.4 version of the Emporix SDK has been released with multi-tenant support.
The SDK now supports running multiple Emporix tenants within a single JVM. This is useful when your application needs to communicate with different Emporix environments (e.g., QA, staging, production) or different tenant accounts simultaneously.
When additional tenants are configured, the SDK automatically creates a full bean stack for each tenant — including EmporixProperties, EmporixClientFactory, EmporixTokenService, and all API clients. These beans are injected using Spring's @Qualifier annotation with the tenant key as the qualifier value.
New features
Multi-tenant configuration
Define additional tenants under emporix.tenants.<key> in application.yml. Each <key> becomes the @Qualifier value for injection.
Property inheritance
Each tenant inherits shared settings (timeouts, cache) from the default configuration. Only differing properties need to be specified.
Custom credentials per tenant
Custom OAuth2 credentials can be defined per tenant, with fallback to the default custom credentials.
Startup validation
The SDK validates multi-tenant configuration at startup and fails fast with descriptive error messages if rules are violated.
Non-intrusive design
Tenant-specific beans are non-default candidates, so they never interfere with unqualified injection or user-provided @Primary overrides.
Availability Service - Q-param support, total count header and search improvements
Overview
The Availability Service has been updated with support for the standard Q-param query parameter on the site-specific endpoint, a Q-param request body option for the search endpoint, and X-Total-Count response header on search endpoints.
Updated endpoints
The response now includes the X-Total-Count header. Added support for the standard q query parameter.
The response now includes the X-Total-Count header. Added support for the standard q request body attribute as an alternative filtering method.
Known problems
There are no known problems.
Product Service – dynamic variant product type and recalculation
Overview
A new product type DYNAMIC_VARIANT has been introduced, enabling flexible multi-level variant hierarchies of up to 4 levels.
Unlike PARENT_VARIANT products, which use a fixed attribute template, DYNAMIC_VARIANT products form a tree where each variant stores its own ownVariantAttributes - these are the attributes that distinguish it from its parent. The root product maintains a denormalized flat map of all descendants in its variants field, with accumulated attributes.
Key features of DYNAMIC_VARIANT products:
Variants can be created in any order — a child variant may exist before its parent, simplifying bulk data imports.
Each variant stores only delta attributes, which are the attributes introduced at its own level. The accumulated, fully merged, attributes are computed by the API at response time by following the
parentVariantIdchain.