Built-in Commerce Connector REST API
Info: The built-in Commerce Connector REST API requires a standard or premium Bloomreach Content license. Contact Bloomreach for details.
Overview
The built-in Commerce Connector REST API exposes JSON endpoints to retrieve data from Commerce Backend Platforms through Commerce Connector Modules. The API serializes the models defined in the Commerce Connector SDK as JSON.
REST API Endpoints
The Commerce Connector REST API is available in both content delivery applications (for example, /site) and content authoring applications (for example, /cms). The following endpoints are available by default:
| Application Type | Endpoint | Description | Example URLs |
|---|---|---|---|
Delivery (e.g., /site) | /restservices/* | Deployed as HST-2 Plain JAX-RS Services. You can customize the mount path using HST-2 configuration. | /site/restservices/categories/, /site/restservices/products/ |
Authoring (e.g., /cms) | /ws/starterstore/* | Deployed as Repository JAX-RS Service. | /cms/ws/starterstore/categories/, /cms/ws/starterstore/products/ |
Commerce Connector Properties REST API
Starting with version 14.3, a dedicated REST API allows you to read selected properties from a specified Commerce Connector. A common use case is for a Single Page Application (SPA) to discover the URL of the brX GraphQL Service by querying the Commerce Connector properties. For implementation details, see Commerce Connector Configuration for brX GraphQL Service.
You can configure additional properties for each Commerce Connector in the Properties field of the Commerce Connector document. To retrieve selected properties, send a GET request to one of the following endpoints:
/ws/starterstore/connectors/{connectorId}/props
(Example: http://localhost:8080/cms/ws/starterstore/connectors/commercetools/props)/restservices/connectors/{connectorId}/props
(Example: http://localhost:8080/site/restservices/connectors/commercetools/props)
The response includes the allowed properties as a JSON object:
{ "apollo.server.url": "https://api.example.com/graphql" }
Each property included in the response corresponds to a property configured in the Commerce Connector document and allowed for exposure.
Configuring Exposable Commerce Connector Properties
For security, the API does not expose all properties by default. Only properties listed in the allowlist.props property are serialized. The allowlist.props value is a comma-separated list of property names.
For example, with the following configuration:
| Property Name | Property Value |
|---|---|
scope | "my_merchant_home" |
role | "my_merchant_role" |
allowlist.props | apollo.server.url, another.api.url |
apollo.server.url | https://api.example.com/graphql |
another.api.url | https://api.example.com/v1 |
A GET request returns:
{ "apollo.server.url": "https://api.example.com/graphql", "another.api.url": "https://api.example.com/v1" }
Properties not listed in allowlist.props (such as scope or role in this example) are excluded from the response.
Info: If
allowlist.propsis not set or is blank, only theapollo.server.urlproperty is exposed by default.
Common Query Parameters
The following query parameters are supported by default:
| Name | Required | Description | Example |
|---|---|---|---|
_connector | No | Identifier of the Commerce Connector to use. If omitted, the Default Commerce Connector for the channel is used. | _connector=brsm |
_offset | No | Offset for paginated results (search APIs only). Defaults to 0. | _offset=10 |
_limit | No | Maximum number of results to return (search APIs only). Defaults to 10. Actual behavior may vary by backend. | _limit=10 |
q | No | Full-text search query (search APIs only). | q=lorem+ipsum |
Category REST API
Category Search
To search categories, send a GET request to /restservices/categories (for example, http://localhost:8080/site/restservices/categories?_connector=brsm). The response includes a collection of categories:
{ "offset": 0, "limit": -1, "totalSize": 42, "facetResult": null, "suggestedActions": { "actions": [] }, "size": 30, "collection": [ { "id": "VPA_VA_MCLASS", "displayName": "M-Class", "children": [ { "id": "VPA_VEHICLE_ADDONS", "displayName": "Addons", "children": [] } ] }, //... { "id": "VPA_T_MICHELIN", "displayName": "Michelin", "children": [ { "id": "VPA_TIRES", "displayName": "Tires", "children": [] } ] }, //... { "id": "VESTRI_APPAREL_MENS", "displayName": "Womens", "children": [ { "id": "VESTRI_BM_APPAREL", "displayName": "Apparel", "children": [] } ] } //... ] }
You can use any of the common query parameters to filter or paginate results.
Category Detail
To retrieve a specific category by categoryId, send a GET request to /restservices/categories/{categoryId} (for example, http://localhost:8080/site/restservices/categories/VPA_VA_MCLASS?_connector=brsm). The response includes the category and its children:
{ "id": "VPA_VA_MCLASS", "displayName": "M-Class", "children": [ { "id": "VPA_VEHICLE_ADDONS", "displayName": "Addons", "children": [] } ] }
Categories are organized hierarchically. Child categories are included in the children property of the parent category.
Product REST API
Product Search
To search products, send a GET request to /restservices/products (for example, http://localhost:8080/site/restservices/products?_connector=brsm). The response includes a collection of products and facet information:
{ "offset": 0, "limit": 10, "totalSize": 66, "facetResult": { "facetFields": [ { "name": "category", "values": [ { "id": "VPA_VA_MCLASS", "parentId": "", "name": "M-Class", "count": 9 }, { "id": "VPA_VEHICLE_ADDONS", "parentId": "", "name": "Vehicle Addons", "count": 8 }, //... { "id": "VSTRI_BM_APPAREL", "parentId": "", "name": "Apparel", "count": 1 } ] }, { "name": "sizes", "values": [ { "id": "large", "parentId": null, "name": "large", "count": 22 }, { "id": "medium", "parentId": null, "name": "medium", "count": 22 }, { "id": "small", "parentId": null, "name": "small", "count": 21 }, { "id": "xlarge", "parentId": null, "name": "xlarge", "count": 14 } //... ] }, { "name": "brand", "values": [] }, { "name": "colors", "values": [ { "id": "red", "parentId": null, "name": "red", "count": 15 }, { "id": "black", "parentId": null, "name": "black", "count": 16 }, //... { "id": "silver", "parentId": null, "name": "silver", "count": 1 } ] } //... ] }, "suggestedActions": { "actions": [] }, "size": 10, "collection": [ { "itemId": { "id": "M-Class-C", "code": "10001" }, "displayName": "M-Class Sports Coupe", "description": "The M-Class Coupe joyful driving demeanor, powerful motors, and stunning styling make it one of the favorite sports cars, as evidenced by its regular appearance on the roads. M-Class Coupe is a focused performance machine, as our electric sports car, its seriousness sets the stage for the rest of the lineup. Enjoy the freedom this can give you.", "imageSet": { "original": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png", "ref": null } } }, "thumbnail": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png", "ref": null } } } }, "listPrice": { "moneyAmounts": [ { "amount": 47999.0, "currency": null, "displayValue": "47999.0" } ] }, "purchasePrice": { "moneyAmounts": [ { "amount": 47999.0, "currency": null, "displayValue": "47999.0" } ] } }, { "itemId": { "id": "T50-PU", "code": "10003" }, "displayName": "T50 SD Pickup Truck", "description": "The Vestri T50 Pickup Truck gives you the tool you need to get the job done. Using an electric/hybrid option you can disappear into remote areas still only supporting the older internal combustion engines. But then switch back to electric power when utility service is available.", "imageSet": { "original": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10003.png", "ref": null } } }, "thumbnail": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10003.png", "ref": null } } } }, "listPrice": { "moneyAmounts": [ { "amount": 44500.0, "currency": null, "displayValue": "44500.0" } ] }, "purchasePrice": { "moneyAmounts": [ { "amount": 44500.0, "currency": null, "displayValue": "44500.0" } ] } }, //... { "itemId": { "id": "HOOD_PANELS", "code": "38186" }, "displayName": "Hood Panels", "description": "Hoods are usually casualties in a front end collision, but they can also suffer damage at the leading edge from airborne road debris, and on the surface from falling objects like hail or tree limbs. Since a typical hood is mostly flat and occupies such a prominent position, any damage stands out and will detract from the vehicle's appearance. A new hood from the dealer is very expensive, but don't let that deter you from making the repair. more details on - https://www.carid.com/replace/hood-panel.html", "imageSet": { "original": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/38186.png", "ref": null } } }, "thumbnail": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/38186.png", "ref": null } } } }, "listPrice": { "moneyAmounts": [ { "amount": 589.0, "currency": null, "displayValue": "589.0" } ] }, "purchasePrice": { "moneyAmounts": [ { "amount": 589.0, "currency": null, "displayValue": "589.0" } ] } } ] }
You can use any of the common query parameters to filter or paginate results.
Product Detail
To retrieve a product by itemId, send a GET request to /restservices/products/{itemIdValue}. The {itemIdValue} path parameter is a concatenation of the id and code fields from the itemId object, separated by three underscores (___). For example, http://localhost:8080/site/restservices/products/M-Class-C___10001/?_connector=brsm.
The response includes product details:
{ "itemId": { "id": "M-Class-C", "code": "10001" }, "displayName": "M-Class Sports Coupe", "description": "The M-Class Coupe joyful driving demeanor, powerful motors, and stunning styling make it one of the favorite sports cars, as evidenced by its regular appearance on the roads. M-Class Coupe is a focused performance machine, as our electric sports car, its seriousness sets the stage for the rest of the lineup. Enjoy the freedom this can give you.", "imageSet": { "original": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png", "ref": null } } }, "thumbnail": { "dimension": null, "links": { "self": { "href": "https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png", "ref": null } } } }, "listPrice": { "moneyAmounts": [ { "amount": 47999.0, "currency": null, "displayValue": "47999.0" } ] }, "purchasePrice": { "moneyAmounts": [ { "amount": 47999.0, "currency": null, "displayValue": "47999.0" } ] } }
Cart REST API
Info: The Cart REST API provides cart data for the current visitor and is available only in the content delivery tier (
/site). It is not available in content authoring (/cms).
Retrieve Cart Data
To get the cart for the current visitor, send a GET request to /restservices/cart/ (for example, http://localhost:8080/site/restservices/cart/).
If a cart exists, the response is HTTP 200 with the following structure:
{ "id": "a25105dc-6301-4a4c-983e-f1a255b89a38", "totalQuantity": 2, "revision": 7, "orderId": null, "entries": [ { "id": "var1-5a64dbea-fed5-422c-9267-42224e9fb2a8", "quantity": 2, "items": [ { "itemId": { "id": "var1-5a64dbea-fed5-422c-9267-42224e9fb2a8", "code": "LeCreuset_SauteusePan" }, "displayName": "Le Creuset Signature Sauteuse Pan", "description": "", "imageSet": { "original": { "dimension": null, "links": { "self": { "href": "https://acc545be1d5fd66d9268-e6ee5bd70ad552747c060c238eaa7bc8.ssl.cf3.rackcdn.com/Le-Creuset-Signature-kTLphxPW.jpg", "ref": null } } }, "thumbnail": { "dimension": null, "links": { "self": { "href": "https://acc545be1d5fd66d9268-e6ee5bd70ad552747c060c238eaa7bc8.ssl.cf3.rackcdn.com/Le-Creuset-Signature-kTLphxPW-thumb.jpg", "ref": null } } } }, "listPrice": { "moneyAmounts": [ { "amount": 479.0, "currency": "USD", "displayValue": "USD 479.0" } ] }, "purchasePrice": { "moneyAmounts": [ { "amount": 479.0, "currency": "USD", "displayValue": "USD 479.0" } ] }, "attributes": { "custom-attribute": "Dune" } } ] }, { "id": "var1-074e7c30-fb98-4cd8-ac96-07207f840d1f", "quantity": 1, "items": [ { "itemId": { "id": "var1-074e7c30-fb98-4cd8-ac96-07207f840d1f", "code": "LeCreuset_Saucepan" }, "displayName": "Le Creuset Signature Saucepan 16cm", "description": "", "imageSet": { "original": { "dimension": null, "links": { "self": { "href": "https://acc545be1d5fd66d9268-e6ee5bd70ad552747c060c238eaa7bc8.ssl.cf3.rackcdn.com/Le-Creuset-Signature-PhVCYq4n.jpg", "ref": null } } }, "thumbnail": null }, "listPrice": { "moneyAmounts": [ { "amount": 349.0, "currency": "USD", "displayValue": "USD 349.0" } ] }, "purchasePrice": { "moneyAmounts": [ { "amount": 349.0, "currency": "USD", "displayValue": "USD 349.0" } ] }, "attributes": {} } ] } ] }
If no cart exists, the response is HTTP 404:
{ "errors": [ { "message": "Cart not found.", "path": null, "code": "404" } ] }
If the backend connector does not support anonymous carts, the response is HTTP 401:
{ "errors": [ { "message": "Expecting a visitor context", "path": null, "code": "401" } ] }