Working with the REST Storefront Cart and Checkout APIs
BigCommerce’s REST Storefront API exposes storefront data to Stencil themes, which lets you manage a shopper’s cart, checkout, and order data using frontend JavaScript. We also offer cart and checkout functionality in the GraphQL Storefront API.
This tutorial exhibits common use cases to help you get started with the REST Storefront API. Each use case contains JavaScript code snippets you can paste into your browser’s console, allowing you to test in the context of your storefront session.
By the end of this tutorial, you should be familiar enough with some of the REST Storefront API endpoints to test them.
Prerequisites
For this tutorial, you will need a BigCommerce store with at least two products and a shipping option.
Getting started
To begin, navigate to your Stencil storefront and open your browser’s developer console.
For this tutorial, set the credentials option to same-origin and the content-type fetch request option to application/json. In production, your credentials will depend on your app setup. See Request.credentials to learn more about other possible values.
REST Storefront Carts
The first part of this tutorial covers using the REST Storefront API to create a cart, add a line item, and delete a line item directly from the storefront.
Create a cart
You can create a cart by sending a request to the Create a cart endpoint.
The following example uses a createCart() helper function to make the API call. To get started, copy and run the following code:
The createCart() function takes two arguments:
route: The endpoint’s request route.cartItems: AlineItemsarray containing product IDs and quantities of the items we want to add.
To create a cart, execute the code below passing in productId values specific to your store.
Your result should be similar to the one below.
Please take note of the value of the cartId as it will be used later in the tutorial.
Get a cart
To display the contents of a cart, we need to send a request to the Get a cart endpoint. By default, the cart response returns abbreviated product details. To get the full product details, we need to add the include query parameter.
Copy and execute the code below to create and subsequently call the getCart() helper function.
Add a cart item
To add a new line item to the existing cart, the ID of the cart must be included in the endpoint. The card ID was returned as part of the “Create a cart” POST request. Alternatively, you can retrieve the cart ID by making a request to the “Get a cart” endpoint. See Add Cart Line Items for more information.
Copy and execute the code below to create the addCartItem() helper function.
Call the function to add a new line item to your cart. Make sure to replace the cartId and productId with your own values.
Delete a cart item
To delete a line item from a cart, send a DELETE request to the Delete Cart Line Item endpoint and pass in the cartId and itemId to be deleted.
Pass your cartId and itemId to the deleteCartItem() helper function to delete the line item.
Storefront Checkout
In this section, we will add a billing address to a checkout, create a consignment, and update a consignment to add a shipping option directly from the storefront. See REST Storefront Checkout for more information.
Before proceeding, make sure you have added two different line items to your cart.
The checkoutId is the same as the cartId.
Add a billing address
To add a billing address to a checkout, send a POST request to the Add Checkout Billing Address endpoint.
Copy and execute the code below to create the addBillingAddress() helper function.
Now call the addBillingAddress() function making sure to replace the cartId with your own value.
Add a new consignment
A consignment consists of a shipping address with the associated line items. At a minimum, you must include one shipping address with line items and shipping options in the checkout. If you use multiple shipping locations, match each lineItem with the correct shipping address. When adding a shipping address to the checkout, include the ?include=consignments.availableShippingOptions query parameter to return the shipping options available for any address.
See Add New Consignment to Checkout for more information.
Create the createConsignment()helper function to test this functionality.
Copy and execute the code below to create a new consignment. Make sure to replace the cartId with your own value.
Update a consignment to add a shipping option
To update a consignment, add your consignmentId and the appropriate shippingOptionId (located inside the availableShippingOptions object) to the PUT request parameters. See Update Checkout Consignment for more information.
Only one consignment can be updated at a time.
Create the updateConsignment() helper function to accomplish this.
Execute the code below to update the consignment, replacing cartId, consigmentId, and shippingOptionId with your values.
Troubleshooting
Did you get a 404? Make sure you have at least one item in your cart. Removing all items deletes the cart and returns a 404 error.
