Admin API v4¶

Welcome to version 4 of the Admin API!

This update brings significant changes aimed at enhancing the product feed experience with our platform. The main focus of this update is a comprehensive redesign of the data feed format, resulting in significant changes to import and export endpoints. Additionally, new endpoints have been introduced to support explicit market configuration of the Elevate server.

Two significant data feed format changes have occurred: firstly, the syntax has transitioned from XML to JSON lines. Secondly, the focus of entity modeling has shifted from markets and locales to product groups and content as the primary import entities. This shift ensures cross-market product selection stability and enables future cross-market behavioral data sharing. Previously, each market required importing individual products. Now, product groups and content are imported once and support overrides as needed.

An introductory overview of the new formats can be found in the Admin v4 Data feed overview section and it's subsections. For detailed guidance on upgrading to Admin v4 from Admin v3, please refer to this Upgrade Guide.

New features¶

Data format features¶

• Modernized data feed format using JSON lines instead of XML
• Greatly reduced import size for imports with overlapping localization and market data
• Updated data modeling to ensure cross market product selection stability and enable future cross market behavioral data sharing
• Introduced support for shared default values for products, variants and content
• Introduced support for shared locale specific overrides for products, variants and content
• Introduced support for shared market specific overrides for products, variants and content
• Introduced a new entity translation, supporting separated, consistent and stable id to name relations for facet and filter attributes
• Added support for adding a product to product groups without having to replace the entire product group
• Added support for adding a variant to a product without having to replace the entire product group
• Introduced support for image ids, supporting standalone updates and additions
• Added new predefined attribute gender, supporting faceting and filtering and utilized by classification
• Added new predefined attribute age, supporting faceting and filtering and utilized by classification
• Added new predefined attribute ontology, enabling a broader set of values for the predefined attribute category to be used for filters and selections
• Added new predefined attribute dataLocale, enabling separation of response data for a given locale and locale to be used for data analysis
• Added support for customJson fields, supporting custom json data with format preservation in query responses

Elevate configuration features¶

• Added an API endpoint configuration allowing stronger market control and enabling market and locale definition modifications independent of data feed
• Introduced support for defining market and locale support without requirement of a data feed import
• Introduced support for deleting all Elevate server market data including merchandising settings such as promotions, benchmarks etc

Other features¶

• Introduced structured error messages with error details in JSON format, enabling further automated error handling
• Introduced Open API Specification for data format

Changes¶

This section lists changes that must be considered when upgrading from Admin v3 to Admin v4.

The listed changes are limited to the resources found in the Admin API and are unrelated to changes and versions of the Storefront API.

Resources¶

Downloadable utility resources.

• Postman collection
• OpenAPI Specification

Endpoints¶

Import¶

• Catalog
• Configuration
• Status
• Navigation
• Pages

Export¶

• Catalog
• Configuration
• Navigation
• Pages

Event data¶

• Create export customer job
• Create remove customer job
• Export customer job result
• Job status

Notifications¶

• Latest
• Payment

Status¶

• Status