Introduction | Storefront API

Introduction of Storefront API

Background

This section provides objective and a solution overview for integrating SHOPLINE by the aids of authenticating with the Storefront API, focusing on enabling different storefront recsource (i.e. cart resources now and many more coming) and ensuring future extensibility for headless commerce scenarios.

The Storefront API eventually will be able to empower developers to build custom shopping experiences. The long-term goal is for the Storefront API to fully replicate the capabilities of a traditional e-shop, supporting a wide range of user experiences and journey.

Solution overview

Calling the Storefront API

1. Logged-in Customers:
   API calls require both a Storefront Access Token and a Customer Access Token.
2. Guest Users:
   API calls require only the Storefront Access Token.

Obtaining Tokens

1. Storefront Access Token
   1. Purpose: Identifies the store and app; used for public access.
   2. How to Obtain: Developer App calls the Admin API endpoint POST /storefront_tokens.
   3. Requires the storefront_tokens scope.
   4. Each Storefront Access Token is tied to a store and does not expire (for public access only).
2. Storefront App Registration
   1. How to Register: Developer App calls Admin API endpoint POST /storefront/oauth_applications.
   2. Requires the storefront/oauth_applications scope.
   3. Each Storefront App is store-specific; supports multiple redirect URIs.
3. Customer Access Token
   1. Purpose: Authenticates a specific customer for personalized operations (e.g., cart).
   2. How to Obtain:
   3. Initiate an OAuth authorization flow
   4. After expiration, refresh using a Refresh Token.

Authentication Flow required under different scenario

1. For Guests:

   1. Only the Storefront Access Token and register storefront app are required.

2. For Customers with logged in:

   1. Get the Storefront Access Token and register storefront app
   2. Initiate Authorization:
      Storefront App starts the OAuth flow to obtain an authorization code.
   3. Exchange Code for Tokens:
      Use the authorization code to get a Customer Access Token and Refresh Token.
   4. Customer Access Token Management

   Tokens are designed to be short-lived for security.

   Token Type	Notes
   Access Token	Used for API calls; short-lived
   Refresh Token	Used to refresh access tokens; longer-lived

Admin API (Open API) Endpoints

Below are for reference, for details and updated version (if any), please refer to the Open API document

Action	Endpoint	Scope	Description
Create Storefront Token	POST /storefront_tokens	storefront_tokens	Create a Storefront Access Token for a store.
Create Storefront App	POST /storefront/oauth_applications	storefront/oauth_applications	Register a Storefront App for a store, specifying redirect URIs and (future) scopes.

Best Practices & Considerations

• Always use HTTPS for all token exchanges and API calls.
• Store Customer access tokens securely; never expose sensitive credentials in client-side code.
• Plan for token expiration and refresh logic in your integration.
• Prepare for future changes, such as application scopes and API versioning.

---