Overview

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).

Shopify

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:

Add the externalId to the base string: "gid://shopify/Product/" + "5009665818763" = gid://shopify/Product/5009665818763
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

BigCommerce

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.

Import

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

Usage

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

How to examples
An opinionated guide to Cart and Checkout pages

About Shogun Frontend

Page Builder for Frontend

Frontend Checkout Cart v3

Frontend Customer

Cart and Checkout