Get started with Configured Commerce REST APIs

15 min

The Optimizely Configured Commerce REST API exposes JSON services that read and write Configured Commerce data in the context of a signed-in user. These API objects and their respective methods are based on common HTTP verbs.

Optimizely built the Storefront API to:

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

Offer an integration and extension point to Configured Commerce.

Allow seamless upgrades.

Put a facade in front of the application so Optimizely can ship improvements 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.

View the API reference with Swagger UI

The Admin, Storefront, and Integration APIs generate an OpenAPI document and serve a Swagger UI that lists every endpoint with its request and response schemas. Use it to explore endpoints and test requests against a running instance while you develop. The Swagger UI is available in non-production environments only; it is disabled in production.

Build a digital commerce workflow with JavaScript and the Storefront API

The following code walks through a basic commerce workflow:

Retrieve the product catalog.

Retrieve all categories.

Search for a product using a query.

Retrieve product details.

Create a wishlist and add products.

Add a product to the shopping cart.

Change the quantity of a product in the shopping cart.

Submit an order.

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 Server before, follow the steps in the Using Fiddler to interact with the API article.

const response = await fetch("/identity/connect/token", {
    method: "POST",
    credentials: "include",
    headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        // This uses the "isc" Identity client.
        Authorization:
            "Basic aXNjOjAwOUFDNDc2LUIyOEUtNEUzMy04QkFFLUI1RjEwM0ExNDJCQw==",
    },
    body: new URLSearchParams({
        username: "admin",
        password: "Password1",
        grant_type: "password",
        scope: "iscapi",
    }),
});

const data = await response.json();
const accessToken = data.access_token;

IThe identity client is a unique public identifier for the application. In Configured Commerce, isc identifies the front end. The /admin/sso/clients page lists every client and application.

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.

const response = await fetch("/api/v1/sessions", {
    method: "POST",
    credentials: "include",
    headers: {
        "Content-Type": "application/json",
        // This uses the access token from the first request.
        Authorization: "Bearer " + accessToken,
    },
    body: JSON.stringify({
        userName: "admin",
        password: "Password1",
    }),
});

const data = await response.json();
console.log("=========== Create a 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 omits the bearer token, because whether the catalog requires authentication depends on the related settings.

const response = await fetch(
    "/api/v1/products?" + new URLSearchParams({ page: 2 }),
    {
        method: "GET",
        headers: {
            Accept: "application/json",
        },
    },
);

const data = await response.json();
console.log("=========== Product Catalog List ============");
console.log(JSON.stringify(data));

Retrieve all categories

const response = await fetch("/api/v1/categories", {
    method: "GET",
    headers: {
        // This uses the access token from the first request.
        Authorization: "Bearer " + accessToken,
    },
});

const data = await response.json();
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.

const response = await fetch(
    "/api/v1/products?" +
        new URLSearchParams({ query: "ancillary sales fleece" }),
    {
        method: "GET",
        headers: {
            Accept: "application/json",
            // This uses the access token from the first request.
            Authorization: "Bearer " + accessToken,
        },
    },
);

const data = await response.json();
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.

const response = await fetch(
    "/api/v1/products?" +
        new URLSearchParams({
            productId: "7b3391f9-4e05-4b60-8f41-9cf600f2e820",
        }),
    {
        method: "GET",
        headers: {
            Accept: "application/json",
            // This uses the access token from the first request.
            Authorization: "Bearer " + accessToken,
        },
    },
);

const data = await response.json();
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.

const response = await fetch("api/v1/wishlists", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        // This uses the access token from the first request.
        Authorization: "Bearer " + accessToken,
    },
    body: JSON.stringify({
        name: "My Wishlist",
    }),
});

const data = await response.json();
console.log("=========== Create WishList Name: My Wishlist ============");
console.log(JSON.stringify(data));
const wishlistId = data.id;

The second request adds a product to the wishlist that was just created.

const response = await fetch(
    "api/v1/wishlists/" + wishListId + "/wishlistlines",
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            // This uses the access token from the first request.
            Authorization: "Bearer " + accessToken,
        },
        body: JSON.stringify({
            productId: "7b3391f9-4e05-4b60-8f41-9cf600f2e820",
            qtyOrdered: 1,
            unitOfMeasure: "EA",
        }),
    },
);

const data = await response.json();
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.

const response = await fetch("api/v1/carts/current/cartlines", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        // This uses the access token from the first request.
        Authorization: "Bearer " + accessToken,
    },
    body: JSON.stringify({
        productId: "7b3391f9-4e05-4b60-8f41-9cf600f2e820",
        qtyOrdered: 1,
    }),
});

const data = await response.json();
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.

const response = await fetch(
    "/api/v1/carts/current/cartlines/9d485b67-7fb9-4935-bb3d-a7bd01124a40",
    {
        method: "PATCH",
        headers: {
            "Content-Type": "application/json",
            // This uses the access token from the first request.
            Authorization: "Bearer " + accessToken,
        },
        body: JSON.stringify({
            // This id is the cartLineId for the specific product.
            id: "9d485b67-7fb9-4935-bb3d-a7bd01124a40",
            qtyOrdered: 2,
        }),
    },
);

const data = await response.json();
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.

const response = await fetch("api/v1/carts/current", {
    method: "PATCH",
    headers: {
        "Content-Type": "application/json",
        // This uses the access token from the first request.
        Authorization: "Bearer " + accessToken,
    },
    body: JSON.stringify({
        // Updated cart with shipping information, payment method, etc.
    }),
});

const data = await response.json();
console.log("=========== Submit Order ============");
console.log(JSON.stringify(data));