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,
externalIdshould be used whenever we deal with the REST API, whilestorefrontIdshould be used when using the GraphQL API.We have a helper that will try a best-effort conversion between
externalIdandstorefrontIdwhen the wrongidtype 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 correctidfor 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
idsfromstorefrontIdtoexternalId.
Generating storefrontId from externalId
The storefrontId can be generated from the externalId.
If you have an externalId of 5009665818763:
Add the
externalIdto the base string:"gid://shopify/Product/" + "5009665818763" = gid://shopify/Product/5009665818763Encode to base64 (which will give you the
storefrontIdwhich isZ2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzUwMDk2NjU4MTg3NjM=)
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