- Menu
- Sitemap
Guide - 7.10 REST API Changes
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)
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.7.3 | Order Submission/OrderHistory (beta) Note This API is a beta version and still subject to changes. | MoneyRO | Attribute currency is no longer read-only. | incompatible | |
Attribute value is no longer read-only. | incompatible | ||||
QuantityRO | Attribute unit is no longer read-only. | incompatible | |||
Attribute value is no longer read-only. | incompatible | ||||
SalesPricingRO | Attribute price is replaced by undiscountedPrice | incompatible | The line item price (single base price x quantity) w/o any discounts | ||
Attribute discountedPrice is replaced by price | incompatible | The line item price (single base price x quantity) w granted item value discounts | |||
Attribute singleBasePrice is replaced by undiscountedSingleBasePrice | incompatible | The base price of one (single base price / quantity) single item w/o any discounts | |||
Attribute discountedSingleBasePrice is replaced by singleBasePrice | incompatible | The base price of one item w/ granted item discounts broken down to one item | |||
Attribute discountedSingleBasePriceRemainder is replaced by singleBasePriceRemainder | incompatible | The remainder of the operation that calculates the singleBasePrice. | |||
ShippingPricingRO | Attribute shippingTotal is replaced by undiscountedShippingTotal | incompatible | The accumulated shipping costs of the line item w/o any shipping discounts. | ||
TotalsRO | Attribute itemTotal is replaced by undiscountedItemTotal | incompatible | The accumulated line item totals w/o any discounts | ||
Attribute discountedItemTotal is replaced by itemTotal | incompatible | The accumulated line item total w/ all granted item value discounts | |||
Attribute shippingTotal is replaced by undiscountedShippingTotal | incompatible | The accumulated shipping costs/charges w/o any discounts | |||
Attribute discountedShippingTotal is replaced by shippingTotal | incompatible | The accumulated shipping costs/charges w/ all granted shipping discounts | |||
New attribute paymentCostsTotal | compatible | Accumulated payment costs of the order | |||
AddressRO | New attribute companyName1 | compatible | First part of addressee's company name | ||
New attribute companyName2 | compatible | Second part of addressee's company name | |||
TaxItemRO | New attribute taxId | compatible | For future use | ||
New attribute taxName | compatible | For future use | |||
New record ImpositionRO | compatible | For future use | |||
JurisdictionRO | New attribute value | compatible | For future use | ||
Attribute level is required now | incompatible | ||||
ImpositionRO | New attribute value | compatible | For future use | ||
New attribute type | compatible | For future use |
2 Storefront REST API
2.1 Authentication API
| Version | API | Element | Change | Migration |
|---|---|---|---|---|
| 7.10.24.1 | authentication | path /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).
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.7.3 | Basket V1 (beta) Note This API is a beta version and still subject to changes. | LineItemRO | Attribute price is replaced by undiscountedPrice and has been moved to Element LineItemPricingRO (former | incompatible | The 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 | incompatible | The line item price (single base price x quantity) w granted item value discounts | |||
Attribute singleBasePrice is replaced by undiscountedSingleBasePrice and has been moved to | incompatible | The 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 | incompatible | The base price of one item w/ granted item discounts broken down to one item | |||
Attribute totals is replaced by pricing. | |||||
LineItemTotalsRO | Element has been renamed to LineItemPricingRO. | incompatible | |||
Attribute totals has been replaced by price. | |||||
BasketTotalsRO | Attribute itemTotal is replaced by undiscountedItemTotal. | incompatible | The accumulated line item totals w/o any discounts | ||
Attribute discountedItemTotal is replaced by itemTotal. | incompatible | The accumulated line item total w/ all granted item value discounts | |||
Attribute shippingTotal is replaced by undiscountedShippingTotal. | incompatible | The accumulated shipping costs/charges w/o any discounts | |||
Attribute discountedShippingTotal is replaced by shippingTotal. | incompatible | The 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 | incompatible | Attributes 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.
| Version | API | Element | Change | Compatibility |
|---|---|---|---|---|
| 7.10.7.3 | Business Customer User List / User Item | UserRO | New method getBirthdayDate() : Date | compatible |
| 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
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.38.9-LTS | Product | ProductsResource | Default categories that are unavailable on the REST interface are no longer included in REST responses. | compatible | The 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-LTS | Product | ProductsResource | SEOMetaAttributes of the product resource returned in a REST call are by default no longer provided by the DetermineMetaTags pipeline. | compatible | The pipeline has been replaced by the java implementation in ProductSEOMetaAttributesHandlerImpl. To return to the pipeline implementation, use PipelineBasedProductSEOMetaAttributesHandlerImpl instead. |
| 7.10.38.9-LTS | Product | ProductListResource | 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. | compatible | Follow-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-LTS | Product | ProductListResource | Limit of 200 for returned products per request added. If a higher value is used as a query parameter "amount", an exception is thrown. | incompatible | This 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 |
|
| 7.10.38.9-LTS | Product | ProductListResource | In 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-LTS | Product | ProductHandler(Impl) |
| compatible | |
| 7.10.35.1 | Product | FilterCollectionRO | In case no search index is found, error code 503 is returned, instead of "500 server error". | compatible | |
| 7.10.27.0 | Product | ProductListResource | The inStock attribute returns data from the inventory service now, instead of data maintained in ICM. | incompatible | Previously the Now the behavior is corrected. In case the
|
| 7.10.27.0 | Product / Promotion | ProductPromotionResource | Improved caching for resource "/products/<sku>/promotions" | compatible | The 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.2 | Product | ProductListResource | Parameter returnSortKeys now returns an additional field sortableAttributes. | compatible | The 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.0 | Product | ProductsResource ProductFiltersResource | New query parameter MasterSKU added | compatible |
|
| 7.10.23.0 | Product | ProductsResource ProductFiltersResource | if configured: new sort order of results | compatible | 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.
Note: If this is not done, the sorting remains as it is right now. |
| 7.10.23.0 | Product | ProductListResource | Support for multiple comma-separated IDs for parameter New field | compatible | If multiple IDs are given, then in the result, the field attributeGroup will be empty, and attributeGroups is used. |
| 7.10.23.0 | Product | AttributeGroupRO | New field displayName added | compatible | |
7.10.21 | Product | SearchIndexFilterResource SearchIndexFilterListResource | Resources are now deprecated. | compatible | |
| 7.10.21 | Product | ProductFiltersResource | Resource is introduced. | compatible | A new resource /productfilters was introduced for the filter REST API. It replaces the (now deprecated) /filters resource. |
| 7.10.21.0 | Product | ProductRO | New field supplierSKU added. | compatible | |
| 7.10.18.0 | Category | CategoryRO | Category 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.0 | Product | ProductRO | New query parameter New field | compatible | |
| 7.10.17.0 | Product | AttachmentRO | New field link added | compatible | |
| 7.10.17.0 | Category and CategoryList | CategoryRO | New query parameter omitHasOnlineProducts added | compatible | |
| 7.10.15.2 | Product List | ProductRO | New attribute in attrs section retailSet | compatible | |
| 7.10.15.2 | Category and CategoryList | CategoryRO | Add functionality for caching the /categories call | compatible | |
| 7.10.10.2 | Product / Product Line Item | DefaultCategoryRO | Extend appendProductSKUToPath(String path, ProductBO product) to show default category | compatible | |
| 7.10.9.0 | Product and Category List | LinkRO | New attribute in attrs section: packingUnit | compatible | |
| 7.10.5.4 | Product List / Product Line Item | LinkRO | New attribute in attrs section: availableStock | compatible | |
| 7.10.5.3 | Product List | AttributeGroupRO | New method getRESTAvailableAttributeGroups(ProductBO product) | compatible | Related: Adding flag in the backoffice if attribute groups should be available in REST. |
| 7.10.5.3 | Product and Category List | LinkRO | New attributes in attrs section: minOrderQuantity and inStock | compatible |
2.5 Customer REST API
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.15.0 | customer/{customerKey}/credentials/password | CustomerPasswordRO | New mandatory attribute currentPassword. | compatible | In order to keep the old behavior it is possible to make currentPassword optional by setting"PasswordUpdateSkipOldPasswordValidation" preference to "true". |
| CredentialsHandler | Signature of method validatePassword changed from validatePassword(UserBO userBO, String password) to validatePassword(UserBO userBO, CustomerPasswordRO passwordRO). | incompatible |
2.6 Security REST API
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.15.0 | security | password | 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 | |
| security | reminder | Changed PasswordReminderResource to require security question answer, firstName and lastName only in case Security Question feature is activated. | compatible |
2.7 Configuration REST API
| Version | API | Element | Change | Compatibility |
|---|---|---|---|---|
| 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
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.19.2 | CMS 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.1 | CMS REST API | PageTreeResource | Resource is introduced to expose the page hierarchy. | compatible |
2.9 Requisition Approval REST API
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.36.0 | /customers/{CustomerKey}/users/{CustomerItemUserKey}/requisitions/{RequisitionKey} |
|
| compatible | Should 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} | ApprovalStatusChangeRO | field "status" was renamed to "statusCode" |
2.10 Promotion REST API
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 7.10.35.1 | Promotion | PromotionResource | Improved caching for resource "/promotions/<promotion-id>" | compatible | The 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.0 | Promotion | PromotionResource | Improved caching for resource "/promotions" | compatible | The 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
| Version | API | Element | Change | Compatibility | Comment |
|---|---|---|---|---|---|
| 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: RetailSets:
Variation Master:
| compatible (extend API) | Still not supported:
|
| 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:
| compatible | Not supported:
|
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.