The Optimizely 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.

Optimizely considered the following when building the Storefront API:

Open up the platform so other platforms can connect to Configured Commerce.
Move customizations to outside the platform.
Let developers build services around the API so the platform offers a developer friendly, flexibility and modern experience.
Offer an integration and extension point to Configured Commerce.
Allow seamless upgrades.
Have a facade in front of the application so improvements can be made with little interruption.
Offer scalability.

The difference between the Storefront API and the Administrative API

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.
Administrative API – Provides data level access to all objects. You can use the Administrative API when integrating other platforms that work with all objects in the Configured Commerce platform, not just those under user or website context.

Build 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 a session.
Retrieve the product catalog.
Retrieve all categories.
Search for a product using a query.
Retrieve product details.
Create a wishlist and add products to it.
Add a product to the shopping cart.
Change the quantity of products in the shopping cart.
Submit an order.

Sign in and create a 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 have not authenticated with Identity Service before, follow the steps in the Using Fiddler to interact with the API article.

$.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;
    }
});

Identity client is a unique public identifier for the application. isc in Configured Commerce means the frontend. You can find a list of all clients and applications at /admin/sso/clients.

📘
Note
isc and its key are hardcoded.

The second request creates a session within the Configured Commerce application, letting the current user manage their account, create wishlists, submit orders, and so on.

$.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 the product catalog

This request retrieves the product catalog available within the current context (such as user, customer, or website). 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 a product using a query

This request lets you search the product catalog with 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 go to it. This request returns the details of a specific product. You may need to change the productId value 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 a wishlist and add products

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 a product to the shopping cart

When you decide upon a product, this request adds 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 the quantity of a product in the shopping cart

If you change your mind about a product, you can update it in the cart using the request below. This specific request increases 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 an order

You can complete your order using the request below. The data in the request must include the current cart updated with shipping information, payment method, and so on.

$.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));
    }
});