Dev GuideAPI ReferenceUser Guide
Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubDev CommunityOptimizely AcademySubmit a ticketLog In
API Reference
GitHubDev CommunityOptimizely AcademySubmit a ticket

Get started with Configured Commerce REST APIs

Describes the Storefront API features and workflow for Optimizely Configured Commerce.

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 javascript and the Storefront API

The following code demonstrates basic commerce work flow usage of the Commerce API.

  1. Sign in and create a session.
  2. Retrieve the product catalog.
  3. Retrieve all categories.
  4. Search for a product using a query.
  5. Retrieve product details.
  6. Create a wishlist and add products to it.
  7. Add a product to the shopping cart.
  8. Change the quantity of products in the shopping cart.
  9. 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.

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;

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.

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 does not include the bearer token because authentication may not be required based 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));

Updated 9 days ago

Next

Updated 9 days ago

Next