Kroger...

Cart Tutorial

In This Tutorial

This tutorial covers how to construct and execute a request to the /carts endpoint. The tutorial also covers how to add an item to a cart that was returned from the product API request, delete an item from a cart, and update a cart. For all cart requests except when creating and retrieving a cart, a user cartId is required.

Introduction to the Cart API

The /carts endpoint allows for clients to create or retrieve a cart, add or remove an item from a cart, and update the cart on the user’s behalf. Updating the cart and adding/removing items from a cart require the cartId obtained from a get/create cart request, and a UPC returned from a product request.

Construct and Execute a Get/Create Cart Request

The get or create cart request is initiated when the user accesses their cart on the demo application. The code below specifies that if a current cart exists, the getCart() function makes a GET request to the /carts endpoint to retrieve the user’s cart. If there is no current cart associated with the user, the createCart() function initiates the same request as a POST to create a cart. All data associated with the cart and products in the cart are returned in the JSON response.

The previously stored access token described in the Authorization Tutorial is used in the “Authorization” header.

cart.js file (client side)

// Get current cart or create new cart
async function getOrCreateCart() {
  const currentCart = await getCart();
  if (currentCart) {
    return currentCart;
  }

  return createCart();
}
// Get cart
async function getCart() {
  // Use stored access token in authorization header
  let accessToken = authentication.getAccessToken();
  // Base URL (https://api.kroger.com)
  // Version/Endpoint (/v1/carts)
  let cartUrl = `${config.apiBaseUrl}/v1/carts`;
  let cartResponse = await fetch(cartUrl, {
    method: "GET",
    cache: "no-cache",
    headers: {
      Authorization: `bearer ${accessToken}`,
      "Content-Type": "application/json; charset=utf-8"
    }
  });

  let carts = await cartResponse.json();
  if (carts.data.length === 0) {
    return null;
  }

  console.log("Returning existing fulfillable cart");
  return carts.data[0];
}
// Create cart
async function createCart() {
  console.log("Creating fulfillable cart");
  let accessToken = authentication.getAccessToken();
  // Base URL (https://api.kroger.com)
  // Version/Endpoint (/v1/carts)
  let cartUrl = `${config.apiBaseUrl}/v1/carts`;
  let cartResponse = await fetch(cartUrl, {
    method: "POST",
    cache: "no-cache",
    headers: {
      Authorization: `bearer ${accessToken}`,
      "Content-Type": "application/json; charset=utf-8"
    },
    // Return json object
    body: JSON.stringify({})
  });

  return cartResponse.json();
}

Request and Response Example

A sample cart request and JSON response are shown below.

Example Cart Request

curl -X GET \
  https://api.kroger.com/v1/carts/f4c5282c-cbd6-4c55-8257-4a808f5ed4d6 \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'Cache-Control: no-cache' 
Example json object structure
{
    "data": {
        "id": "f4c5282c-cbd6-4c55-8257-4a808f5ed4d6",
        "name": "Fulfillable",
        "items": [
            {
                "allowSubstitutes": true,
                "createdDate": "2018-09-17T18:50:50.659+0000",
                "quantity": 1,
                "specialInstructions": "specialInstructions",
                "upc": "0000000004139",
                "description": "Apple - Granny Smith - Small"
            },
            {
                "allowSubstitutes": true,
                "createdDate": "2018-09-06T18:10:47.521+0000",
                "quantity": 1,
                "specialInstructions": "",
                "upc": "0000000004023",
                "description": "Grapes - Red Seedless"
            },
            {
                "allowSubstitutes": true,
                "createdDate": "2018-09-06T18:10:47.521+0000",
                "quantity": 1,
                "specialInstructions": "",
                "upc": "0000000004022",
                "description": "Grapes - White Seedless"
            },
            {
                "allowSubstitutes": true,
                "createdDate": "2018-09-06T18:10:47.521+0000",
                "quantity": 1,
                "specialInstructions": "",
                "upc": "0001111041600",
                "description": "Kroger 2% Reduced Fat Milk"
            }
        ],
        "createdDate": "2018-08-10T14:35:53.138+0000"
    },
    "meta": {}
}
A Product UPC is required for the remaining steps of this tutorial. If you have not implemented the Product API and only wish to retrieve or create a user cart, you can skip to the end of the tutorial.

Update the Cart Wrapper

The async function updateCart() shown below is used in the code as a wrapper for all of the following cart requests:

  • Adding an item to the cart (POST)
  • Removing an item from the cart (DELETE)
  • Updating the cart (PUT)

The wrapper runs the same code for all cart API requests, only changing the HTTP method and required query parameters.

Update Cart Wrapper

async function updateCart(url, apiMethod, item) {
  let accessToken = authentication.getAccessToken();
  return await fetch(url, {
    method: apiMethod,
    cache: "no-cache",
    headers: {
      Authorization: `bearer ${accessToken}`,
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify(item)
  });
}

Add an Item and Update the Cart

The addOrUpdateCartOnClick(event) is initiated when the user clicks the “add to cart” button in the HTML. The function checks to make sure that all of the required data was returned from the product request for the item associated with the button.

To add an item to the cart, the getOrCreateCart() function from the earlier example makes a request to determine if there is an existing cart or if a new cart needs to be created for the user. The cartId in the JSON response is used as a parameter for all other requests.

The updateCart() function either initiates a POST or a PUT request depending on whether the item UPC already exists in the cart. The updated cart is then returned with either a new item added to the cart or an updated quantity for an item that already existed in the cart.

cart.js file (client side) Cont.

async function addOrUpdateCartOnClick(event) {
  let upc = event.target.value;
  if (!upc) {
    alert("No identifiable UPC code was found.");
    return;
  }

  let quantityElement = document.getElementById(upc + "Quantity");
  if (!quantityElement || !quantityElement.value) {
    alert("No Quantity was found");
    return;
  }

  if (quantityElement.value < 1) {
    alert("No Quantity was added");
    return;
  }

  addOrUpdateCart({
    quantity: parseInt(quantityElement.value),
    allowSubstitutes: true,
    specialInstructions: "",
    upc: upc
  });
}

async function addOrUpdateCart(item) {
  console.log("Adding item to cart");

  let cart = await getOrCreateCart();
  // If current item exists, update cart quantity
  let currentItem = checkCartForItem(item.upc, cart);
  if (currentItem) {
    console.log("Updating quantity");
    currentItem.quantity += item.quantity;
    // Update cart quantity based on existing quantity
    // Base URL (https://api.kroger.com)
    // Version/Endpoint (/v1/carts/)
    // Query String (${cart.id}/items/${currentItem.upc})
    let putUrl = `${config.apiBaseUrl}/v1/carts/${cart.id}/items/${
      currentItem.upc
    }`;
    return await updateCart(putUrl, "PUT", {
      quantity: currentItem.quantity,
      allowSubstitutes: item.allowSubstitutes,
      specialInstructions: item.specialInstructions
    });
  }
  // Add item to cart URL
  // Base URL (https://api.kroger.com)
  // Version/Endpoint (/v1/carts/)
  // Query parameters (${cart.id}/items)
  let postUrl = `${config.apiBaseUrl}/v1/carts/${cart.id}/items`;
  return await updateCart(postUrl, "POST", item);
}
// Checking for quantity
function checkCartForItem(upcCode, cart) {
  console.log("Checking cart");

  return cart.items.find(function(item) {
    return item.upc === upcCode;
  });
}

Remove an Item from the Cart

The removeItemFromCartOnClick(event) is initiated when the user clicks the “remove from cart” button in the HTML. The getOrCreateCart() function then makes another request, determining if a cart exists. The returned cartId and item UPC are passed as a parameter in the DELETE request, using the updateCart() function.

cart.js file (client side) Cont.

// Remove item from cart
async function removeItemFromCartOnClick(event) {
  console.log("Removing Item from cart");
  let upc = event.target.value;
  if (!upc) {
    alert("No identifiable UPC code was found.");
    return;
  }
  // Get current cartId for query parameter
  let cart = await getOrCreateCart();
  // Build remove item URL
  // Base URL (https://api.kroger.com)
  // Version/Endpoint (/v1/carts/)
  // Query String (${cart.id}/items/${upc})
  let removeUrl = `${config.apiBaseUrl}/v1/carts/${cart.id}/items/${upc}`;
  // Update wrapper
  return updateCart(removeUrl, "DELETE", null);
}

Next Steps

Now that you have seen one possible way to implement the Cart API, we recommend checking out some of our other tutorials. You can also visit our Documentation Page to learn more about implementing Kroger APIs.

For more information on the /carts endpoints, see our Swagger Documentation Page.