[{"value":"In this page, you will learn about:","id":"in-this-page-you-will-learn-about","hLevel":2,"level":1},{"value":"What is a Custom Storefront?","id":"what-is-a-custom-storefront","hLevel":2,"level":1},{"value":"Scenarios for headless commerce","id":"scenarios-for-headless-commerce","hLevel":2,"level":1},{"value":"Creating a storefront access token","id":"creating-a-storefront-access-token","hLevel":2,"level":1},{"value":"Access Endpoints","id":"access-endpoints","hLevel":2,"level":1},{"value":"Rate Limiting Policy","id":"rate-limiting-policy","hLevel":2,"level":1},{"value":"Status and error codes","id":"status-and-error-codes","hLevel":2,"level":1},{"value":"Usage examples","id":"usage-examples","hLevel":2,"level":1}]

Overview

The Storefront API provides comprehensive capabilities for customizing pages such as products, orders, shopping carts, and checkouts.

Quickly build storefront pages for your store using your preferred technology stack and frontend development frameworks.
Using SHOPLINE backend data and business capabilities, create any type of headless e-commerce model.
Customize customer pages using the Storefront API on any platform (HTML5, Native Apps, or Web).

In this page, you will learn about:

The concept of custom storefronts
Scenarios and advantages of headless commerce
Creating a Storefront Access Token
Rate limiting and status codes for the Storefront API

What is a Custom Storefront?

A custom storefront is a way to implement the headless commerce model, where the frontend and backend of the store are decoupled.

The frontend and business processes are implemented by developers, while the e-commerce transactional flow and data storage are supported and implemented by the SHOPLINE e-commerce engine.

When the desired business system architecture, business processes, and customer experience cannot be achieved using SHOPLINE's existing sales channel capabilities, themes, and apps, consider building a custom storefront if:

You are familiar with and proficient in a web frontend development framework but not familiar with HandleBars.
Your shopping experience is unique from the typical browse products, add to cart, and proceed to checkout flow, and requires more flexible handling of various business processes.
You want to integrate SHOPLINE's transaction capabilities into your existing business architecture system.

Scenarios for headless commerce

The SHOPLINE Storefront API supports not only e-commerce website development, but also other types of transaction experiences, such as mobile apps, paid videos, in-app purchases, and knowledge payments, including:

Selling products from mobile apps or web apps (PWA).
Selling products or services from IoT devices.
Selling content or memberships on video websites.
Adding purchase buttons to existing CMS systems to sell products or content.

Key advantages custom storefronts offer:

High flexibility:

The Storefront API is device, environment, and platform agnostic, allowing you to build frontend pages using any programming language.
High level of customization:

You can build a solution that can adapt and grow with the merchant's business. As sales trends and product selections change, your custom storefront can be replaced and adapted to meet evolving market needs.

Creating a storefront access token

Once a store has granted the app Unauthenticated scopes authorization, the app can call the Create Storefront Access Token endpoint in the Admin REST API to obtain a Storefront Access Token. This token can then be used to directly access the Storefront API with the Unauthenticated scopes permissions bound to it.

Access Endpoints

The Storefront API can only be accessed via the POST method, with the following endpoint:

POST https://{storeCustomDomain}.myshopline.com/storefront/graph/v20220901/graphql.json

storeCustomDomain refers to the custom domain of the store, and v20220901is the version of the API.

You can modify the version number in the endpoint according to your actual situation.

Rate Limiting Policy

The Storefront API supports transactions of any scale and can dynamically increase access limits based on the number of customers in the store, so you don't have to worry about the impact on buyer access as your store's transaction volume grows.

To protect against machine access, access to the Storefront API must originate from real users. We provide time-based rate limiting at the IP level, using a leaky bucket algorithm with bucket size and leak rate to limit both burst and sustained request rates:

Per Second / App / IP: 1 second of compute resources
Bucket Size: 60 seconds of compute resources

For example, when a customer first accesses the Storefront API, the IP can consume a maximum of 60 seconds of compute resources in the first second, and after the first second, it can only consume 1 second of compute resources per second.

Status and error codes

All Storefront API requests will return HTTP status codes. Please refer to the HTTP status code for more details.

Usage examples

curl --location --request POST 'https://openapiceshidianpu.myshopline.com/storefront/graph/v20230301/graphql.json' \
--header 'Accept-Encoding: gzip, deflate, br' \
--header 'Content-Type: app/json' \
--header 'Accept: app/json' \
--header 'Connection: keep-alive' \
--header 'DNT: 1' \
--header 'Origin: file://' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ0b2tlbiI6IjU4YmYwZjFiYjA3ZWU2ZmU3ZjQzNGQxMGU0ODlhN2U0OGMwZGZiYTJ8Njc3NDd8MTY3MjM2OTcyOTYwNnwxNjcyNzEyODczMzQ0IiwiaXNzIjoieXNvdWwifQ.teC5ht0if8yZlzWUQa-oOS43ZEG5_m7KzPgijpwCYISuAIPp6D15Bxm9e_5O60Ue4JHsfbM8c1jN0koQIt3oSw' \
--data-raw '{"query":"\n\nquery{\n  blogs(first:10){\n    pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},\n    edges{cursor,node{id,title,author,handle,onlineStoreUrl}}\n  }\n}\n"}'