Describes the Storefront API features and workflow.
The Configured Commerce REST API is made up of RESTful-based services that interact with Configured Commerce data within the context of user interaction using JSON objects. These API objects and their respective methods are based on common HTTP verbs.
The following were considerations when the Storefront API was built:
- Open up the platform so other platforms can connect to Configured Commerce (connected commerce).
- Move customizations to outside the platform.
- Allow developers to build services around the API so the platform offers a developer friendly, flexibility and modern experience.
- Integration and extension point to Configured Commerce.
- Allow for seamless upgrades.
- Facade in front of the application so improvements can be made with little interruption.
- Scalability.
What is the difference between the Storefront API vs Administrative API?
The Storefront API delivers digital commerce functionality such as viewing products related to a website, adding products to a user's cart, and working with user account information. Whereas the Administrative API provides data level access to all objects. The Administrative API can be used when integrating other platforms where there is a need to work with all objects in the Configured Commerce platform, not just those under user or website context.
Building a digital commerce workflow using jQuery and the Storefront API
The following code demonstrates basic commerce work flow usage of the Commerce API.
- Sign In and Create B2B Session
- Retrieve Product Catalog
- Retrieve All Categories
- Search for Product Using a Query
- Retrieve Product Details
- Create Wishlist and Add Product to Wish List
- Add Product to Shopping Cart
- Change Quantity of Product in Shopping Cart
- Submit Order
Sign In and Create Session
Signing into Configured Commerce involves two requests: one to authenticate with Identity Server and a second to create a Configured Commerce session.
The first request authenticates you with Identity Server. If you haven't before authenticated with Identity Server, you can follow the steps in the Using Fiddler to interact with the API article to find out how.
$.ajax({
url: "/identity/connect/token",
type: "POST",
crossDomain: true,
xhrFields: { withCredentials: true },
data: {
username: "admin",
password: "Password1",
"grant_type": "password",
scope: "iscapi"
},
beforeSend: function(xhr) {
// This uses the "isc" Identity client.
xhr.setRequestHeader("Authorization", "Basic aXNjOjAwOUFDNDc2LUIyOEUtNEUzMy04QkFFLUI1RjEwM0ExNDJCQw==");
},
success: function(data) {
console.log(JSON.stringify(data));
// Save the access token for subsequent requests.
commerceToken = data.access_token;
}
});
The second request creates a session within the Configured Commerce application, allowing the current user to manage his or her account, create wishlists, submit orders, etc.
$.ajax({
url: "/api/v1/sessions",
type: "POST",
data: {
userName: "admin",
password: "Password1"
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function(data) {
console.log("=========== Create an B2B Session ============");
console.log(JSON.stringify(data));
}
});
Retrieve Product Catalog
This request retrieves the product catalog available within the current context (e.g. user, customer, website). Notice that this request does not include the bearer token because authentication may not be required based on the related settings.
$.ajax({
url: "/api/v1/products",
type: "GET",
data: {
page: 2
},
dataType: "json",
success: function (data) {
console.log("=========== Product Catalog List ============");
console.log(JSON.stringify(data));
}
});
Retrieve All Categories
$.ajax({
url: "/api/v1/categories",
type: "GET",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function(data) {
console.log("=========== Get All Categories ============");
console.log(JSON.stringify(data));
}
});
Search for Product Using a Query
This request allows the product catalog to be searched given a query.
$.ajax({
url: "/api/v1/products",
type: "GET",
data: {
query: "ancillary sales fleece"
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function (data) {
console.log("=========== Search for Product Using a Query ============");
console.log(JSON.stringify(data));
}
});
Retrieve Product Details
Once a product has been found using search, you can navigate to it. This request returns the details of a specific product. The "productId" value may need to change based on the data available in your Configured Commerce application.
$.ajax({
url: "/api/v1/products",
type: "GET",
data: {
productId: "7b3391f9-4e05-4b60-8f41-9cf600f2e820"
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function(data) {
console.log("=========== Get Product Details ============");
console.log(JSON.stringify(data));
}
});
Create Wishlist and Add Product to Wish List
If you want to remember a product for later, you can create a wishlist and add the product to it.
The first request creates a new wishlist for the current user given a name.
$.ajax({
url: "api/v1/wishlists",
type: "POST",
data: {
name: "My Wishlist"
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function(data) {
console.log("=========== Create WishList Name: My Wishlist ============");
console.log(JSON.stringify(data));
// Save the wishListId subsequent requests.
wishListId = data.id;
}
});
The second request adds a product to the wishlist that was just created.
$.ajax({
// This uses the wishListId from the first request.
url: "api/v1/wishlists/" + wishListId + "/wishlistlines",
type: "POST",
data: {
productId: "7b3391f9-4e05-4b60-8f41-9cf600f2e820",
qtyOrdered: 1,
unitOfMeasure: "EA"
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function (data) {
console.log("=========== Add Product to Wishlist ============");
console.log(JSON.stringify(data));
}
});
Add Product to Shopping Cart
When you've decided upon a product, this request will add it to the cart with a specific quantity.
$.ajax({
url: "api/v1/carts/current/cartlines",
type: "POST",
data: {
productId: "7b3391f9-4e05-4b60-8f41-9cf600f2e820",
qtyOrdered: 1
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function(data) {
console.log("=========== Add Product to Shopping Cart ============");
console.log(JSON.stringify(data));
}
});
Change Quantity of Product in Shopping Cart
If you've changed your mind about a product, you can update it in the cart using the request below. This specific request will increase the quantity ordered.
$.ajax({
url: "/api/v1/carts/current/cartlines/9d485b67-7fb9-4935-bb3d-a7bd01124a40",
type: "PATCH",
data: {
// This id is the cartLineId for the specific product.
id: "9d485b67-7fb9-4935-bb3d-a7bd01124a40",
qtyOrdered: 2
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function(data) {
console.log("=========== Change Quantity of Product in Shopping Cart ============");
console.log(JSON.stringify(data));
}
});
Submit Order
Finally, you can complete your order using the request below. The data in the request will need to include the current cart updated with shipping information, payment method, etc.
$.ajax({
url: "api/v1/carts/current",
type: "PATCH",
data: {
// Updated cart with shipping information, payment method, etc.
},
dataType: "json",
beforeSend: function(xhr) {
// This uses the access token from the first request.
xhr.setRequestHeader("Authorization", "Bearer " + commerceToken);
},
success: function (data) {
console.log("=========== Submit Order ============");
console.log(JSON.stringify(data));
}
});