Related Documents
Document Properties
Kbid
290M43
Last Modified
06-Sep-2022
Added to KB
04-Mar-2019
Public Access
Everyone
Status
Online
Doc Type
Guidelines, Concepts & Cookbooks
Product
ICM 7.10

Guide - 7.10 REST API Changes

Product Version

7.10

Product To Version


Status

1 Intershop Commerce Management REST API

There are the following changes in basket/order related REST APIs to:

  • Get a stringent naming scheme (SalesPricingRO, ShippingPricingRO, TotalsRO)
  • Avoid errors in generated Swagger schema (MoneyRO, QuantityRO)
  • Be prepared for future use (TaxItemRO, JurisdictionRO, ImpositionRO)
VersionAPIElementChangeCompatibilityComment
7.10.7.3

Order Submission/OrderHistory (beta)

Note

This API is a beta version and still subject to changes.

MoneyROAttribute currency is no longer read-only.incompatible
Attribute value is no longer read-only.incompatible
QuantityROAttribute unit is no longer read-only.incompatible
Attribute value is no longer read-only.incompatible
SalesPricingROAttribute price is replaced by undiscountedPrice incompatibleThe line item price (single base price x quantity) w/o any discounts
Attribute discountedPrice is replaced by price incompatibleThe line item price (single base price x quantity) w granted item value discounts
Attribute singleBasePrice is replaced by undiscountedSingleBasePrice
incompatibleThe base price of one (single base price / quantity)  single item w/o any discounts
Attribute discountedSingleBasePrice is replaced by singleBasePrice incompatibleThe base price of one item w/ granted item discounts broken down to one item
Attribute discountedSingleBasePriceRemainder is replaced by singleBasePriceRemainder incompatibleThe remainder of the operation that calculates the singleBasePrice.
ShippingPricingROAttribute shippingTotal is replaced by undiscountedShippingTotal incompatibleThe accumulated shipping costs of the line item w/o any shipping discounts.
TotalsROAttribute itemTotal is replaced by undiscountedItemTotal incompatibleThe accumulated line item totals w/o any discounts
Attribute discountedItemTotal is replaced by itemTotal incompatibleThe accumulated line item total w/ all granted item value discounts
Attribute shippingTotal is replaced by undiscountedShippingTotal incompatibleThe accumulated shipping costs/charges w/o any discounts
Attribute discountedShippingTotal is replaced by shippingTotal incompatibleThe accumulated shipping costs/charges w/ all granted shipping discounts
New attribute paymentCostsTotalcompatibleAccumulated payment costs of the order
AddressRONew attribute companyName1 compatibleFirst part of addressee's company name
New attribute companyName2 compatibleSecond part of addressee's company name
TaxItemRO

New attribute taxId compatibleFor future use
New attribute taxName compatibleFor future use
New record ImpositionRO compatibleFor future use
JurisdictionRONew attribute value compatibleFor future use
Attribute level is required nowincompatible
ImpositionRONew attribute value compatibleFor future use
New attribute type compatibleFor future use

2 Storefront REST API

2.1 Authentication API

VersionAPIElementChangeMigration
7.10.24.1authenticationpath /logout

Value of path in UserTokenResource (no API) of endpoint '/logout' changed to 'token/logout'.

Adapt urls in client calls. Use 'token/logout' instead of 'token'.

2.2 Basket V1 REST API

In the Storefront Basket V1 REST APIs there are the following changes:

  • Get a stringent naming scheme (LineItemRO, LineItemTotalsRO, BasketTotalsRO).
  • Simplify handling of custom attributes (ExtensibleRO).
VersionAPIElementChangeCompatibilityComment
7.10.7.3







Basket V1 (beta)

Note

This API is a beta version and still subject to changes.

LineItemROAttribute price is replaced by undiscountedPrice and has been moved to Element LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe line item price (single base price x quantity) w/o any discounts
Attribute discountedPrice is replaced by price and has been moved to LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe line item price (single base price x quantity) w granted item value discounts
Attribute singleBasePrice is replaced by undiscountedSingleBasePrice and has been moved to LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe base price of one (single base price / quantity) single item w/o any discounts
Attribute discountedSingleBasePrice is replaced by singleBasePrice and has been moved to LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe base price of one item w/ granted item discounts broken down to one item
Attribute totals is replaced by pricing.

LineItemTotalsROElement has been renamed to LineItemPricingRO.incompatible
Attribute totals has been replaced by price.

BasketTotalsRO


Attribute itemTotal is replaced by undiscountedItemTotal. incompatibleThe accumulated line item totals w/o any discounts
Attribute discountedItemTotal is replaced by itemTotal.incompatibleThe accumulated line item total w/ all granted item value discounts
Attribute shippingTotal is replaced by undiscountedShippingTotal.incompatibleThe accumulated shipping costs/charges w/o any discounts
Attribute discountedShippingTotal is replaced by shippingTotal.incompatibleThe accumulated shipping costs/charges w/ all granted shipping discounts
Attribute paymentCostTotal is replaced by paymentCostsTotal.

ExtensibleRO (and all inheriting elements: AddressRO, BasketRO, LineItemRO, ShippingMethodRO)

Method ExtensibleRO::getAttributes() : Map<String, Collection<String>> has been replaced by ExtensibleRO::getAttributes() : Collection<AttributeRO<?>>.

incompatibleAttributes are contained in the data section of JSON payload of related elements instead of the includes section.

2.3 Business Customer User List / User Item REST API

Storefront Business Customer User List / User Item REST API was extended:

  • Business Customer Users List resource GET method previously showed the current logged user. It was changed to list all actual users of the customer;
  • Added POST method to Business Customer Users List resource to create one or multiple new users for the customer;
  • Added DELETE method to Business Customer User Item resource to remove customer's user;
  • Altered PUT method of Business Customer User Item resource - previously it only allowed the current logged user to change their own attributes; now admin user can change values of other users which belong to the same customer.
VersionAPIElementChangeCompatibility
7.10.7.3

Business Customer User List / User ItemUserRONew method getBirthdayDate() : Datecompatible
SMBCustomerUserRO

New methods:

getPreferredInvoiceToAddressUrn() : String

setPreferredInvoiceToAddressUrn(String)

getPreferredShipToAddressUrn() : String

setPreferredShipToAddressUrn(String)

compatible

New classes in app_sf_rest_smb cartridge

SMBCustomerUserROCollection

UserLinkRO

UserLinkROCollection

compatible

2.4 Product and Category REST API

VersionAPIElementChangeCompatibilityComment
7.10.38.9-LTSProductProductsResourceDefault categories that are unavailable on the REST interface are no longer included in REST responses.compatibleThe defaultCategory property is omitted and not included in the response. The PWA treats this attribute as optional. Other UIs may need to be updated.
7.10.38.9-LTSProductProductsResourceSEOMetaAttributes of the product resource returned in a REST call are by default no longer provided by the DetermineMetaTags pipeline. compatibleThe pipeline has been replaced by the java implementation in ProductSEOMetaAttributesHandlerImpl. To return to the pipeline implementation, use PipelineBasedProductSEOMetaAttributesHandlerImpl instead.
7.10.38.9-LTSProductProductListResource

A configurable limit for returned products per request was added. If a higher amount value is used as a query parameter (default limit: 200), a 400 Bad Request Error will be returned. 

compatibleFollow-up to the change below: If absolutely necessary, you can adjust the limit using the property intershop.rest.maxProductAmount to restore API function.
7.10.38.9-LTSProductProductListResource

Limit of 200 for returned products per request added. If a higher value is used as a query parameter "amount", an exception is thrown.

incompatibleThis is a security measure to avoid unnecessarily high load on the ICM. For PWAs with paging, this is not an issue.
7.10.38.9-LTS

Product

ProductsResource

ProductListResource


Authenticated calls for the resources ProductsResource and ProductListResource will now check if the provided spgid matrix parameter matches with the user. When a spgid is provided, and there is a mismatch, a 400 Bad Request Error will be returned.incompatible
  • Previously, it was only checked whether a spgid was specified or not.
    • This resulted in incorrectly cached prices, e.g., when a default spgid such as  "undefined" was used in the request.
  • The spgid of a user can be requested via the PersonalizationResource.
  • If no spgid is provided, the request will be handled as an anonymous request as before this change.
7.10.38.9-LTSProductProductListResourceIn case no search index is found, error code 503 is returned.compatible

Removed fallback to database search. 

If the database search has been customized in your project, you can simply switch back to the old product handler that still uses the old pipelines and contains the database fallback.


7.10.38.9-LTSProductProductHandler(Impl)
  • ProductHandlerImpl was deprecated, a new implementation was added
  • In ProductHandler getProducts and getProductsBySimpleSearch were replaced with more meaningful methods
  • /products?productFilter=... and /categories/<...>/products?productFilter=... now works consistently
compatible

see Guide - 7.10.38.9 Rest API ProductHandler Rework

7.10.35.1ProductFilterCollectionROIn case no search index is found, error code 503 is returned, instead of "500 server error".compatible
7.10.27.0ProductProductListResourceThe inStock attribute returns data from the inventory service now, instead of data maintained in ICM.incompatible

Previously the inStock and availability fields both returned the value of the "in stock" checkbox of a product in the ICM. This was wrong and did not match the documentation.

Now the behavior is corrected. In case the inStock attribute was previously used, an adjustment is required:

  • inStock returns inventory data from the inventory service (boolean; empty in case there is no active inventory service)
  • availableStock returns the stock level of a product from a quantity-based inventory service
  • availability returns the value of the "in stock" as maintained in the ICM
7.10.27.0Product / PromotionProductPromotionResourceImproved caching for resource "/products/<sku>/promotions"compatibleThe result list of promotions is now personally cached; for personalized promotions a "spgid" matrix parameter is mandatory, either as part of "products" or "promotions". The caching time now depends on the end dates of involved promotions (valid until first promotion becomes invalid). If "spgid" is missing for authorized requests the result for anonymous users is returned.
7.10.26.2ProductProductListResourceParameter returnSortKeys now returns an additional field sortableAttributes.compatibleThe parameter returnSortKeys, when true, will return a list of sort keys for the search query in the field sortKeys. Now, an additional field sortableAttributes is returned as well, with more detailed information on the sort keys, such as direction and display name.
7.10.23.0Product

ProductsResource

ProductFiltersResource

New query parameter MasterSKU addedcompatible

MasterSKU can now be indexed in the search index, similar to MasterUUID. This is needed so MasterSKU can be used in the REST API, e.g. to filter /products and /productfilters for a given variation master. (The REST API only handles skus, not UUIDs.)

  • Add new attribute "MasterSKU" to the index, with the same settings as "MasterUUID".
    • Recommendation: Keep the name "MasterSKU". If not, make a note of the new defined name so you can use it later in the REST API - this is the name of the query parameter.
    • Rebuild the search index.
  • Now you can use the “MasterSKU” query parameter as described in the REST API documentation.
7.10.23.0Product

ProductsResource

ProductFiltersResource

if configured: new sort order of resultscompatible

Variation products on variation master pages, as well as in the REST API (/products?MasterSKU=<sku>) can now be sorted as defined in the backoffice, if no other sorting is specified. This requires configuration of the search index.

  • create new index attribute
    • name: VariationPosition
    • data provider: ProductPO
    • data type: Double
  • rebuild search index

Note: If this is not done, the sorting remains as it is right now.

7.10.23.0ProductProductListResource

Support for multiple comma-separated IDs for parameter attributeGroup

New field attributeGroups in result if multipe IDs were given.

compatibleIf multiple IDs are given, then in the result, the field attributeGroup will be empty, and attributeGroups is used.
7.10.23.0ProductAttributeGroupRONew field displayName addedcompatible

7.10.21

Product

SearchIndexFilterResource

SearchIndexFilterListResource

Resources are now deprecated.

compatible


7.10.21ProductProductFiltersResource

Resource is introduced.

compatibleA new resource /productfilters was introduced for the filter REST API. It replaces the (now deprecated) /filters resource.
7.10.21.0ProductProductRONew field supplierSKU added.compatible
7.10.18.0CategoryCategoryROCategory endpoint now support category references as a category id, replacing the previous categoryRef query parameter. Format: /categories/<category id or ref>incompatible
7.10.17.0ProductProductRO

New query parameter extended added

New field variationAttributeValuesExtended added

compatible
7.10.17.0ProductAttachmentRONew field link addedcompatible
7.10.17.0Category and CategoryListCategoryRONew query parameter omitHasOnlineProducts addedcompatible
7.10.15.2Product ListProductRONew attribute in attrs section retailSet
compatible
7.10.15.2Category and CategoryListCategoryROAdd functionality for caching the /categories callcompatible
7.10.10.2Product / Product Line ItemDefaultCategoryROExtend appendProductSKUToPath(String path, ProductBO product) to show default categorycompatible
7.10.9.0Product and Category ListLinkRONew attribute in attrs section: packingUnit compatible
7.10.5.4Product List / Product Line ItemLinkRONew attribute in attrs section: availableStock compatible
7.10.5.3Product ListAttributeGroupRO

New method getRESTAvailableAttributeGroups(ProductBO product)

compatibleRelated: Adding flag in the backoffice if attribute groups should be available in REST.
7.10.5.3Product and Category ListLinkRONew attributes in attrs section: minOrderQuantity  and inStock compatible

2.5 Customer REST API

VersionAPIElementChangeCompatibilityComment
7.10.15.0

customer/{customerKey}/credentials/passwordCustomerPasswordRO

New mandatory attribute currentPassword.

compatibleIn order to keep the old behavior it is possible to make currentPassword optional by setting"PasswordUpdateSkipOldPasswordValidation" preference to "true".


CredentialsHandlerSignature of method validatePassword changed from validatePassword(UserBO userBO, String password) to validatePassword(UserBO userBO, CustomerPasswordRO passwordRO).incompatible

2.6 Security REST API

VersionAPIElementChangeCompatibilityComment
7.10.15.0

securitypassword

Added new sub-resource "password" allowing to set new password - part of the "Forgot Password" feature.

New REST resource com.intershop.sellside.rest.common.capi.resource.credentials.PasswordResetResource with one POST method resetPassword.

New resource object com.intershop.sellside.rest.common.capi.resourceobject.PasswordResetRO

New interface com.intershop.sellside.rest.common.capi.resource.credentials.handler.PasswordResetHandler

compatible

securityreminderChanged PasswordReminderResource to require security question answer, firstName and lastName only in case Security Question feature is activated.compatible

2.7 Configuration REST API

VersionAPIElementChangeCompatibility
7.10.20.0

Configuration V1 (beta)

Note

This API is a beta version and still subject to changes.


ConfigurationRO

Change of the response data structure from list to map representation.

Payload before the change:
{
    "data":
		[
        	{
        	    "applicationType": "intershop.B2CResponsive",
            	"default": true,
	            "id": "application",
	            "urlIdentifier": "-"
    	    },...
		]
}
Payload after the change:
{
    "data": 
		{
        	"application": {
        	    "applicationType": "intershop.B2CResponsive",
        	    "default": true,
        	    "id": "application",
        	    "urlIdentifier": "-"
        	},...
		}
}
incompatible

2.8 CMS REST API

VersionAPIElementChangeCompatibilityComment
7.10.19.2CMS REST API
The REST API documentation was extended to explain the proper usage of personalized requests for the CMS REST API.compatible
7.10.18.1CMS REST API

PageTreeResource

Resource is introduced to expose the page hierarchy.

compatible

2.9 Requisition Approval REST API

VersionAPIElementChangeCompatibilityComment
7.10.36.0/customers/{CustomerKey}/users/{CustomerItemUserKey}/requisitions/{RequisitionKey}

RequisitionRO

  • New field "approvalStatuses" which contains all already handled Approval Steps
  • systemRejected is now part of the RequisitionRO
compatibleShould be used from RequisitionRO, instead of RequisitionRO.approvalStatus from now on
7.10.25.0

/customers/{CustomerKey}/users/{CustomerItemUserKey}/requisitions/{RequisitionKey}ApprovalStatusRO

field "status" which was the status code before is now stored in field "statusCode" and the field "status" now contains a localized status text



7.10.25.0/customers/{CustomerKey}/users/{CustomerItemUserKey}/requisitions/{RequisitionKey}ApprovalStatusChangeROfield "status" was renamed to "statusCode"

2.10 Promotion REST API

VersionAPIElementChangeCompatibilityComment
7.10.35.1PromotionPromotionResourceImproved caching for resource "/promotions/<promotion-id>"compatibleThe promotion details are now also personally cached like the promotion lists. Details for a promotion can only be retrieved when the promotion is accessible to the requested user.
7.10.27.0PromotionPromotionResource

Improved caching for resource "/promotions"

compatibleThe result list of promotions is now personally cached; for personalized promotions a "spgid" matrix parameter is mandatory, either as part of "products" or "promotions". The caching time now depends on the end dates of involved promotions (valid until first promotion becomes invalid). If "spgid" is missing for authorized requests the result for anonymous users is returned.

2.11 Product Price REST API

VersionAPIElementChangeCompatibilityComment
7.10.38.9-LTS

Product Price V1 (beta)

Note

This API is a beta version and still subject to changes.

ProductPriceResource

Now RetailSets and Variation Master products are fully supported:
Instead of List and Sale Price the following Prices (net and/or gross) are returned:

RetailSets:

  • Min list and/or sale price
  • Summed up list and/or sale price

Variation Master:

  • Min list and/or sale price
  • Max list and/or sale price
compatible
(extend API)
Still not supported:
  • Warranties
7.10.32.0-LTS

Product Price V1 (beta)

Note

This API is a beta version and still subject to changes.

ProductPriceResource

A new Product Price REST API has been implemented which allows an uncached access of product prices including scaled prices.

The following features are supported:

  • B2C and B2B
  • customer-specific prices
  • prices for multiple products in one request
  • net and/or gross prices in one request (configurable via query parameter)
  • list and/or sale prices in one request (configurable via query parameter)
  • scaled prices included (fixed price or percentage discount)

compatible
(new API)

Not supported:
  • Retail Sets
  • Variation Master
  • Warranties

2.12 Rating & Review REST API

VersionAPIElementChangeCompatibilityComment
7.10.38.14-LTSRating & ReviewReviewItemResource (ReviewRO)The item details of a review now contain the boolean attribute own which reflects whether the review was created by the currently authenticated user.

compatible

(extend API)

own flag was only available in the list so far
7.10.38.14-LTSRating & ReviewReviewItemResource (ReviewRO)The item details of a review now contain a new processable "statusCode". It reflects the status of the review.
Possible values are "NEW", "APPROVED", "REJECTED". The statusCode "APPROVED" is also used for reviews that are immediately visible without approval.

compatible

(extend API)

Field "status" remains unchanged.
7.10.38.14-LTSRating & ReviewReviewListResourceWhen new reviews are created, now title and content of a review are checked for profanity.

no API change


3 Contact Center REST API

VersionAPIElementChangeCompatibilityComment
7.10.38.14-LTSUser DetailsUserResource (UserRO)The details of a user (Contact Center Account Representative) now contain the string attribute login in addition to firstname and lastname.

compatible

(extend API)


Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets