API

14 min

The Optimizely Configured Commerce REST API is made up of RESTful-based services that interact with 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 Commerce API was built:

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 flexible and modern experience.

Provide integration and extension points to Configured Commerce.

Allow seamless upgrades.

Let developers make improvements with few interruptions.

Offer scalability.

What is the difference between the Commerce API and the Administrative API?

The Commerce 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 platform, not just those under the user or website context.

Build a digital commerce workflow using jQuery and the Commerce API

The following code demonstrates basic commerce workflow usage of the Commerce API:

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

Signing into Optimizely involves two requests: one to authenticate with Identity Server and a second to create a session.

The first request authenticates you with Identity Server. If you have not yet authenticated with Identity Server in Configured Commerce, see Interact with the API using FiddlerInteract with the API using Fiddler.

$.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 Configured Commerce, letting the current user manage their account, create wish lists, 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 ISC Session ============");  
        console.log(JSON.stringify(data));  
    }  
});

Retrieve product catalog

This request retrieves the product catalog available within the current context (such as 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 go 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 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 wish list and add the product to it.

The first request creates a new wish list 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 wish list 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 decide on 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 Quantity of Product in 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 Order

Finally, 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, and so on.
    },
    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));
    }
});

Working with APIs

See Get started with Configured Commerce REST APIsGet started with Configured Commerce REST APIs to learn more.

API