Frontend Checkout
Updated over a week ago


The frontend-checkout package is used for fetching products, adding/removing products in the cart, and retrieving the checkout URL. This is an agnostic provider interface to access and manipulate shopping cart elements, and initiate checkouts.

Backend considerations

We need to provide a set of credentials for all cloud providers, so the API requests are correctly handled.

These APIs, in particular for using the REST endpoints are limited by the Same-Origin Policy, and they can only be called by the same origin.

Platforms considerations

frontend-checkout provides a unified and agnostic API in the form of the useCartState and useCartActions hooks. Nonetheless, there are some differences between the data format of the providers currently supported (Shopify and BigCommerce).


For Shopify, you'll need to provide a storefront token and a shared secret. To obtain those credentials you'll have to follow these steps: Authenticate a private app with the Shopify admin.

It is important to know the difference between storefrontId and externalId. Both are the same, but storefrontId is encrypted using base64.


  • For a checkout point of view, externalId should be used whenever we deal with the REST API, while storefrontId should be used when using the GraphQL API.

  • We have a helper that will try a best-effort conversion between externalId and storefrontId when the wrong id type is provided for the store's API type. However, this conversion is not guaranteed to succeed, and is only in place as a fallback. To ensure no unforeseen issues happen with your cart, please make sure you use the correct id for your Shopify API type.

  • Our cart hooks can only use one API at a time, which is now set to default - GraphQL. To change which API is being used, Shogun would need to change its configuration in the backend and you would need to switch ids from storefrontId to externalId.

Generating storefrontId from externalId

The storefrontId can be generated from the externalId.

If you have an externalId of 5009665818763:

  1. Add the externalId to the base string: "gid://shopify/Product/" + "5009665818763" = gid://shopify/Product/5009665818763

  2. Encode to base64 (which will give you the storefrontId which is Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzUwMDk2NjU4MTg3NjM=)

Generating externalId from storefrontId:

Decode string using Base64.

If you have Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzUwMDk2NjU4MTg3NjM=, decoding it will give you: gid://shopify/Product/5009665818763


For BigCommerce, you'll need to provide a Client ID, Access Token (Storefront API Tokens - manage), and the Storefront Hash. To obtain those values you'll have to follow these steps:

Retrieving ID

Unlike Shopify, BigCommerce just uses an id, which you can retrieve as a section variable in Frontend. No conversion is needed.

Unsupported features

frontend-checkout currently don't support:

  • Coupons

  • Gift cards

  • Discounts

  • Tax calculations

The above is handled by each platform's checkout pages.


frontend-checkout is already pre-installed on every Shogun Frontend store. It exposes useCartState and useCartActions hooks. To import:

import { useCartState, useCartActions } from 'frontend-checkout'

API reference


For an in depth guide on how to use the frontend-checkout:

Did this answer your question?