Cart and Checkout

Storefront Cart and Checkout

The Storefront APIs are for managing the contents of a shopper’s cart and checkout using JavaScript in the context of a storefront session.

When to Use the Storefront APIs

Analytics and Tracking
Retrieving cart data client-side
Quick Order Form
Upsell applications

Using the Fetch API

The Fetch API is an alternative to XMLHttpRequest for making http requests in JavaScript. You can use the Fetch API to interact with the Storefront APIs and return a shopper’s cart, checkout or order.

Fetch API is supported by most modern browsers, but it is not supported in Internet Explorer. We recommend using a Polyfill for Internet Explorer 10+ and XMLHttpRequest for earlier versions.

To learn more about using the Fetch API with the Storefront see our tutorial here.

You can run fetch requests from the browser console to test, or you can use the Scripts API to add inject JavaScript into your theme’s footer.

Log Cart Details to the Console

<script>
console.log('Log Cart');
fetch('/api/storefront/cart', {
  credentials: 'include'
}).then(function(response) {
  return response.json();
}).then(function(myJson) {
  console.log(myJson);
});
</script>

Log Checkout Details to the Console

<script>
console.log('Log Checkout');
fetch('/api/storefront/cart?includes=consignments.availableShippingOptions', {
        credentials: 'include'
      })
      .then(function(response) {
        return response.json();
      }).then(function(cartJson) {
        console.log(cartJson);
        return cartJson[0].id;
      }).catch(function(error) {
        console.log(error);
      }).then(function(cartId) {
        fetch('/api/storefront/checkouts/' + cartId, {
          credentials: 'include'
        }).then(function(response) {
          return response.json();
        }).then(function(checkoutJson) {
          console.log(checkoutJson);
        }).catch(function(error) {
          console.log(error);
        })
      });

</script>

Log Order Details to the Console

<script>
console.log("Log Order");
fetch('/api/storefront/order/{{checkout.order.id}}', {credentials: 'include'})
.then(function(response) {
return response.json();
})
.then(function(myJson) {
console.log(myJson);
});
</script>

Server-to-Server Cart and Checkout

The Server-to-Server APIs are for managing the contents of a shopping cart and checkout remotely, from a server. Using the Cart, Checkout and Payment API allows for a fully headless ecommerce solution.

CaaS

Commerce-as-a-Service is made possible with the Server-to-Server APIs. It lets the underlying cart, checkout, order and payment APIs be called from a separate app, allowing you to create a completely custom checkout without ever touching the BigCommerce storefront.

When to Use

Modifying cart contents, such as price matching
Taking a shopper through cart and checkout using an app
Quote Builder - Building a cart then restoring it on the storefront
Native mobile apps
Pre-filling customer information

Troubleshooting Cart Errors

We will go over common Storefront Cart and Checkout as well as Server to Server Cart and Checkout errors. Each scenario will include the error message and how to fix the error. The most common errors are listed below.

Please create some text for the API option [422]

Server to Server Cart API

Issue: When a cart is created containing a product that has an incorrect or missing text modifier.

Resolution: Options and modifiers refer to a list of choices on a product. Options are used to build out variants and modifiers are not tied to variants at all. To learn more about options and modifiers see Products Overview.

To add a product to the cart that has a single modifier (text field), POST to the Cart API without the variant_id.

Single Modifier

{
  "line_items": [
    {
      "quantity": 1,
      "product_id": 1001,
      "option_selections": [
        {
          "option_id": 123,
          "option_value": "Hello!"
        }
      ]
    }
  ]
}

To add a product to the cart that has one option (radio button) associated with it, use just the variant_id in the request.

Single Option

{
  "line_items": [
    {
      "quantity": 1,
      "product_id": 1001,
      "variant_id": 2331
    }
  ]
}

To add a product that has both an option and a modifier associated with it, then use the option_id and option_value. This example uses a radio button (option) and a text field (modifier).

Modifier and Option

{
  "line_items": [
    {
      "quantity": 1,
      "product_id": 101,
      "option_selections": [
        {
          "option_id": 231,
          "option_value": 456
        },

        {
          "option_id": 123,
          "option_value": "Hello!"
        }
      ]
    }
  ]

Missing line_items in request body [422]

Server to Server Cart API

Issue: When a required product modifier is missing. A product can have a modifier that is not required. In those cases the product can be added to a cart without the modifier.

Resolution: Use the Get Products or Get Modifier endpoints to return the modifier ID. The modifier_id = option_id.

To create a cart with a product modifier:

Create cart with modifier

{
  "line_items": [
    {
      "quantity": 1,
      "product_id": 1001,
      "option_selections": [
        {
          "option_id": 123,
          "option_value": "Hello!"
        }
      ]
    }
  ]
}

A shipping address for this order is incomplete [422]

Server to Server Cart API

Issue: This can return when the customer ID of a cart has changed.

Resolution: The customer ID is linked to discounts and pricing available to that customer. If that is changed then anything that affects the cart price is invalidated. This includes coupons, discounts, taxes and shipping.

A cart should be created with the customer_id as part of the request body. Use the Get Customers endpoint to get the customer_id.

To create a cart with a customer_id:

Create cart with customer ID

{
  “customer_id”: 12,
  "line_items": [
    {
      "quantity": 5,
      "product_id": 191
    }
  ]
}

This product has options, variant ID is required [422]

Server to Server Cart API

Issue: When a product has options and variant ID is not supplied in either the create or update cart request.

Resolution: To get the variant ID use the Get Products endpoint or the Get Variants endpoint. To create a cart with a variant ID:

Create cart with variant ID

{
  "line_items": [
    {
      "quantity": 1,
      "product_id": 1001,
      "variant_id": 2331
    }
  ]
}

Issue: The incorrect option_id is supplied.

Resolution: To get the correct option_id make a request to Get Products or Get Options.

Create cart option ID

{
  "line_item": {
    "quantity": 1,
    "product_id": 76,
    "list_price": 170,
    "option_selections": [
      {
        "option_id": 21506,
        "option_value": 10090
      }
    ]
  }
}

Storefront Cart API

Issue:

Missing required modifier on the storefront. This can include a text modifier with no selection. Make sure the optionValue is not blank.
The variantID is incorrect.
The modifierID is incorrect.

Resolution: To add a product to the cart that has a single modifier (text field), POST to the Cart API without the variant_id. Use the optionId and optionValue instead.

Create cart optionId and optionValue

{
  "lineItems": [
    {
      "quantity": 1,
      "product_id": 1001,
      "optionSelections": [
        {
          "optionId": 123,
          "optionValue": "Hello!"
        }
      ]
    }
  ]
}

To add a product to the cart that has one option (radio button) associated with it, use just the variant_id in the request.

Create Storefront Cart variantID

{
  "lineItems": [
    {
      "quantity": 1,
      "productId": 1001,
      "variantId": 2331
    }
  ]
}

To add a product that has both an option and a modifier associated with it, then use the option_id and option_value. This example uses a radio button (option) and a text field (modifier).

Add item with option and modifier

{
  "lineItems": [
    {
      "quantity": 1,
      "product_id": 101,
      "optionSelections": [
        {
          "optionId": 231,
          "optionValue": 456
        },
        {
          "optionId": 123,
          "optionValue": "Hello!"
        }
      ]
    }
  ]
}

You can only purchase a maximum of :qty of the :product per order [409]

Server to Server Cart API

Issue: When less than a product’s minimum required purchase or more than the maximum allowed purchase is added to cart.

Resolution: Check the product for order_quantity_minimum and order_quantity_maximumfor the correct amount to add the cart. Use the Get Product endpoint.

Internal Server Error [500]

Server to Server Cart API

Issue: Adding more product quantity to a cart than what’s in stock.

Resolution: Check the product for inventory_level to see how many are in stock. Use the Get Product endpoint.

Issue: Trying to edit a Cart that does not exist.

Resolution: Carts are only valid 30 days past the date_last_modified. Check the Get Carts endpoint for the current available session cart.

Storefront Cart API

Issue: When less than a product’s minimum required purchase or more than the maximum allowed purchase is added to cart. Use the Get Product endpoint to check for min/max purchase restrictions.

Resolution: Check the product for order_quantity_minimum and order_quantity_maximum for the correct amount to add the cart. Use the Get Product endpoint.

Available Webhooks

OAuth Scopes

Carts
Checkouts
Products
Checkout Content
Order Transactions

For more details and a full list of available scopes, see Oauth Scopes.

Cart and Checkout

On This Page

Storefront Cart and Checkout

When to Use the Storefront APIs

Using the Fetch API

Server-to-Server Cart and Checkout

CaaS

When to Use

Troubleshooting Cart Errors

Please create some text for the API option [422]

Missing line_items in request body [422]

A shipping address for this order is incomplete [422]

This product has options, variant ID is required [422]

You can only purchase a maximum of :qty of the :product per order [409]

Internal Server Error [500]

Available Webhooks

OAuth Scopes

Related Endpoints