Overview
The Product Details service is a mashup service of the Product, Price, and Category services. It enables you to display rich product information in a product detail view by retrieving data from multiple core and commerce services in a single GET request.
The service calls backing services asynchronously and in parallel and handles errors and time-outs gracefully.
API Reference
/{tenant}/productdetails
/{tenant}/productdetails
Get products with default prices.
/{tenant}/productdetails/{productId}
Get product details including default price and categories.
Scopes in the Product Details Service
You can use scopes to specify exactly what type of permissions a user needs to access resources and perform operations.
The Product Details service makes use of scopes that are defined for the Product, Category, and Price services. For example:
- To get the details of an unpublished product, the user must be assigned a role with the hybris.product_read_unpublished scope.
- If a user queries for a product that belongs to an unpublished category, the user can only retrieve that product data if they have a role with the hybris.category_read_unpublished scope assigned.
To learn more about scopes, see the following documentation:
For more information about the authorization and authentication used in SAP Hybris services, see the following documentation:
Get Product Details List
Customers can check the details of any product available in the tenant. The Product Details service provides product detail information, including the product's current price.
Request
To get the product details list, you need:
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/productdetails/v2/{tenant}/productdetails - Headers:
- accept-language: This restricts the set of natural languages preferred as a response to the request. You can provide fallback language codes separated by commas. Each language range can be given an associated quality value that represents an estimate of the user's preference for the languages specified by that range. This quality value defaults to
q=1. - hybris-languages: Use the asterisk (
*) character to get all available product translations. - hybris-currency: The value of this header is relayed to the Price service in order to return the prices in the required currency. Currency is defined by its ISO code.
- Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from the OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization. For more information about the scopes in the Product Details service, see Scopes in the Product Details Service.
- accept-language: This restricts the set of natural languages preferred as a response to the request. You can provide fallback language codes separated by commas. Each language range can be given an associated quality value that represents an estimate of the user's preference for the languages specified by that range. This quality value defaults to
- Query Parameters: Query parameters are optional. You can use them to influence the results.
- q: The value is relayed to the Product service and used to add value constraints on products. For example, to retrieve product details for products with the name sampleName, make a GET request on the
/{tenant}/productdetails?q=name:"sampleName"resource. For more information, see Search for Objects and Sort Search Results in the Document service documentation. - sort: The value is relayed to the Product service and used to sort constraints on products. For example, to retrieve product details that are sorted in descending order by name, perform a GET request on the
/{tenant}/productdetails?sort=name:descresource. For more information, see the Sort Objects by Localized Attributes topic in the Document section. - pageNumber: The value is relayed to the Product service and used for paging purposes. To specify which page of results should be retrieved, specify the pageNumber, starting from 1. If a page number is specified, the pageSize attribute should also be provided.
- pageSize: The value is relayed to the Product service and used to set the maximum number of product detail elements to be returned in the request.
- effectiveDate: The value is relayed to the Price service and used to limit price collection to prices that are valid in a specified effectiveDate. For example, products contain price promotions which are already outdated. If you do not want these in the response, use the effectiveDate query parameter. For example, you can use
/{tenant}/productdetails/{productId}?effectiveDate=2015-03-20T22:00:00+0000to retrieve product information with the prices collection containing prices which are valid for the specified date.
- q: The value is relayed to the Product service and used to add value constraints on products. For example, to retrieve product details for products with the name sampleName, make a GET request on the
Response
The Product Details service communicates with the Product, Category, and Price services to provide the requested results. To get all the required data, the related services must be alive and provide their own responses.
- One localized attribute is returned as string value if the appropriate accept-language header is provided.
- If you do not provide either the accept-language or appropriate hybris-languages headers, then all localized attributes are returned as simple string values.
- If the hybris-languages header is provided with the asterisk character (
*) as the value, then all available translations are returned.
Status code
The successful response includes a status code of 200.
Examples
Response body with simple translation:
{ "product":{ "id": "538c6120104e74a3c955671e", "code": "ProductNr11400250658627", "name": "Product Nr 1" }, "prices": [ { "priceId": "55003515f50e7a65abbc7a01", "originalAmount": 50, "effectiveAmount": 50, "currency": "USD" }, { "priceId": "55003515f50e7a65abbc7a02", "originalAmount": 40, "effectiveAmount": 40, "currency": "USD", "dateRange": { "startDate": "2015-03-01T01:00:00.000Z", "endDate": "2015-03-01T23:00:00.000Z" } }, { "priceId": "55003515f50e7a65abbc7a03", "originalAmount": 5, "effectiveAmount": 5, "currency": "USD", "dateRange": { "startDate": "2010-01-01T22:00:00.000Z", "endDate": "2010-03-25T01:00:00.000Z" } } ] }, { "product":{ "id": "123c6120104e74a3c9556123", "code": "ProductNoPrice", "name": "Product with no price" } }, ...Response body with translation map:
{ "product":{ "id": "538c6120104e74a3c955671e", "code": "ProductNr11400250658627", "name": { "en":"English Test Product 2 Name", "de":"Ein Deutsches Produkt" } }, "categories": [], "prices": [ { "priceId": "55003515f50e7a65abbc7a01", "originalAmount": 50, "effectiveAmount": 50, "currency": "USD" }, { "priceId": "55003515f50e7a65abbc7a02", "originalAmount": 40, "effectiveAmount": 40, "currency": "USD", "dateRange": { "startDate": "2015-03-01T01:00:00.000Z", "endDate": "2015-03-01T23:00:00.000Z" } }, { "priceId": "55003515f50e7a65abbc7a03", "originalAmount": 5, "effectiveAmount": 5, "currency": "USD", "dateRange": { "startDate": "2010-01-01T22:00:00.000Z", "endDate": "2010-03-25T01:00:00.000Z" } } ] }
The result consists of two or three parts:
- Data such as id, code, and name comes from the Product service.
- Data such as the prices collection comes from the Price service.
- Data such as categories comes from the Category service. Again, this is returned only for a single product. If the query returns more then one product, the category is not returned for those products.
If any of the related services are not active or the response time exceeds the configured time-out, there are three possible scenarios:
- Timeout to Price Service Exceeded: The Product service can return the product information, but the product details response does not include the price field. The status code of this response is
203. An additional Warning header is returned that contains an appropriate message, such asmissing_price. - Timeout to Product Service Exceeded: The Product service cannot return the product information. An error is returned.
- Timeout to Category Service Exceeded: The category could not be retrieved from the Category service. The status code of this response is
203. The Product Details service returns the requested data, but does not include any information from the Category service. The status code of this response is203. An additional Warning header is returned that contains an appropriate message.
Get Product Details
Customers can check all of the details of any product available in the tenant. The Product Details service provides product detail information, including the product's current price and the categories to which the product belongs.
Request
To get the product details, you need:
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/productdetails/v2/{tenant}/productdetails/{productId} - Headers:
- accept-language: This restricts the set of natural languages preferred as a response to the request. You can provide fallback language codes separated by commas. Each language range can be given an associated quality value that represents an estimate of the user's preference for the languages specified by that range. The quality value defaults to
q=1. - hybris-languages: This header is responsible for keeping the information about languages. Use the asterisk (
*) character to get all available product translations. - hybris-currency: The value of this header is relayed to the Price service in order to return prices in the required currency. Currency is defined by its ISO code.
- Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from the OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization. For more information about the scopes in the Product Details service, see Scopes in the Product Details Service.
- accept-language: This restricts the set of natural languages preferred as a response to the request. You can provide fallback language codes separated by commas. Each language range can be given an associated quality value that represents an estimate of the user's preference for the languages specified by that range. The quality value defaults to
Response
The Product Details service communicates with the Product, Category, and Price services to provide the requested results. To get all the required data, the related services must be alive and provide their own responses. The Product Details service combines the data from the Product, Category, and Price services to create a response of its own.
- One localized attribute is returned as string value if the appropriate accept-language header is provided.
- If you do not provide either the accept-language or appropriate hybris-languages headers, then all localized attributes are returned as simple string values.
- If the hybris-languages header is provided with the asterisk character (
*) as the value, then all available translations are returned.
Status code
The successful response includes a status code of 200.
Examples
- Response body with simple translation:
{ "product":{ "id": "538c6120104e74a3c955671e", "code": "ProductNr11400250658627", "name": "Product Nr 1" }, "categories": [], "prices": [ { "priceId": "55003515f50e7a65abbc7a01", "originalAmount": 50, "effectiveAmount": 50, "currency": "USD" }, { "priceId": "55003515f50e7a65abbc7a02", "originalAmount": 40, "effectiveAmount": 40, "currency": "USD", "dateRange": { "startDate": "2015-03-01T01:00:00.000Z", "endDate": "2015-03-01T23:00:00.000Z" } }, { "priceId": "55003515f50e7a65abbc7a03", "originalAmount": 5, "effectiveAmount": 5, "currency": "USD", "dateRange": { "startDate": "2010-01-01T22:00:00.000Z", "endDate": "2010-03-25T01:00:00.000Z" } } ] } - Response body with translation map:
{ "product":{ "id": "538c6120104e74a3c955671e", "code": "ProductNr11400250658627", "name": { "en":"English Test Product 2 Name", "de":"Ein Deutsches Produkt" } }, "categories": [], "prices": [ { "priceId": "55003515f50e7a65abbc7a01", "originalAmount": 50, "effectiveAmount": 50, "currency": "USD" }, { "priceId": "55003515f50e7a65abbc7a02", "originalAmount": 40, "effectiveAmount": 40, "currency": "USD", "dateRange": { "startDate": "2015-03-01T01:00:00.000Z", "endDate": "2015-03-01T23:00:00.000Z" } }, { "priceId": "55003515f50e7a65abbc7a03", "originalAmount": 5, "effectiveAmount": 5, "currency": "USD", "dateRange": { "startDate": "2010-01-01T22:00:00.000Z", "endDate": "2010-03-25T01:00:00.000Z" } } ] }
The result consists of three parts:
- Data such as id, code, and name comes from the Product service.
- Data such as the prices collection comes from the Price service.
- Data such as categories comes from the Category service. If no category is assigned to the returned product, it is an empty table.
If any of the related services are not active or the response time exceeds the configured time-out, there are three possible scenarios:
- Timeout to Price Service Exceeded: The Product service can return the product information, but the product details response does not include the price field. The status code of this response is
203. An additional Warning header is returned that contains appropriate message, such asmissing_price. - Timeout to Product Service Exceeded: The Product service cannot return the product information. An error is returned.
- Timeout to Category Service Exceeded: The category could not be retrieved from the Category service. The status code of this response is
203. The Product Details service returns the requested data, but does not include any information from the Category service. The status code of this response is203. An additional Warning header is returned that contains appropriate message.
Error Types
For more information about error codes, see the API Reference.
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.