Square Online Custom Sites

Enables access to site code to support full or partial customization of Square Online stores.

Millions of sellers use Square Online to sell products or services and grow their customer base. Square Online’s flexible customization options give sellers granular control over the look and feel of their site and enable unique and branded online experiences for buyers. Using Square Online’s customization features, web developers working on behalf of sellers can create custom sites and pages that integrate directly with items and categories from the site catalog.

Visit Square’s Brisk demo site to see some of the possibilities.

Screenshot of the homepage of the Kombu demo site.

Customizing the checkout page is not supported - see limitations.

Scenarios

Square Online’s custom site capabilities enable developers to provide online experiences such as:

  • Consistent branding across online and in-store experiences.
  • Immersive experiences synchronized with the site catalog.
  • Specialized flows for targeted campaigns or throughout the buyer journey.
  • Engaging splash pages for new products and best sellers.
  • Ability to build a custom cart experience before initiating Square’s checkout flow.

In this documentation, the term developer refers to the web designer or design agency hired by a Square seller to customize their site.

How it works

Square sellers have unrestricted access to the underlying code of their Square Online sites, except cart and checkout pages. When a seller hires you to customize their site, you’ll need authorization from the seller to access their site code and settings. After that, you can create a new site or add custom pages to an existing site.

During this Alpha phase, custom sites functionality is only available for new sites created in a multi-site environment for participating sellers. After creating a new site in the seller’s Square Online dashboard, you must initialize the site by opening it in the site editor (click Edit site in the dashboard). Then, you can use the Square Online CLI to initialize the site’s theme and manage site and theme files locally. You also need to provide your application ID and the Seller’s User ID to the Square team so they can add you to the allow list for custom site development. For more information, see Get Started.

Account setup and authorization

First, you need to set up your developer accounts and obtain authorization from the seller. During development, you’ll typically work from the seller’s Square Online dashboard and from a local development environment.

Step Documentation
Create and configure a Weebly for Web Designers account. Set Up Your Weebly for Web Designers Account
Request access to the seller’s Square Online dashboard. Using your Weebly for Web Designers account, you’ll request access to the seller’s Square Online account. You’ll use the seller’s Square Online dashboard to create a new site, preview changes to the site, and publish the site. You can also use it for other tasks, such as managing site settings, updating the catalog, and using the code editor. Manage Access to the Square Online Dashboard
Create a Square account and application. Set Up Your Square Account
Obtain an access token to call Square APIs. You’ll use your Square account credentials to obtain an access token that allows you to run Square Online CLI commands to initialize a theme for a new site and manage site files locally. Manage Access to Square APIs
Choose a site development option. You must consult with the seller to decide whether to develop against an existing site or a new site in a multi-site environment. Choose Existing or New Site Development Option

Customizing site code

You can start coding after you obtain authorization. For example, you can create a custom site and add .json pages with .twig templates. In your templates, you’ll use supported template syntax to access site resources and use Square client SDK or API calls for site actions, such as validating items and manipulating the cart. Otherwise, you are free to choose your preferred JavaScript libraries and CSS classes for general website development.

Step Documentation
Learn about the directory structure of a custom site. Site files have a specific organization in site and theme directories. Site Architecture Overview
Learn how templates are used for page rendering. .twig template files are used with .json files to render page content. Page Rendering with Templates
Create a new site in a multi-site account. Custom site development often starts with creating a new site from the seller’s Square Online dashboard.
Note: After you create the site, you need to click Edit site to make it accessible to the Square Online CLI, which you’ll use to install a theme on the site.		 Manage Access to the Square Online Dashboard

Manage Multiple Websites with Square Online
Initialize a custom theme on a new site. Use the Square Online CLI to install a custom theme on a new site and then manage site and theme files locally. Get Started
Learn about supported template syntax. Use tags, filters, and functions in your templates to render dynamic content and enable template reuse. We recommend that you access resources using template syntax for more efficient caching. Template Syntax Reference
Learn what you can do with the SDK. The SDK provides functions that simplify site actions, such as managing the cart. Site Theme SDK
Learn how to do specific tasks. Create a page, access the site catalog, integrate site features, and more. How Tos

In the Get Started tutorial, you’ll use the CLI to create a custom theme (that uses starter files for the retail vertical), download site files to your local development environment, and upload and preview your changes.

Supported Square Online features

The following core Square Online features are currently supported for custom sites:

  • Shipping fulfillment
  • Pickup fulfillment
  • Fulfillment scheduling
  • Locations
  • Discounts
  • Customer accounts login
  • Loyalty
  • Videos
  • Customer reviews
  • Gift options
  • Pre-orders
  • Delivery fulfillment
  • Time-based categories
  • Subscriptions

The following core features are not yet supported:

  • Afterpay
  • Customization of the customer account management
  • Custom attributes

Documentation and other developer resources

Square provides the following developer resources for developing custom sites:

Resource Description
Get Started, Guides, and How Tos Setup, conceptual, and how-to information related to custom site development.
Kombu site A demo site that showcases some of the things you can do with custom site development.
Brisk Retail Template Starter files for the retail vertical that helps you get a custom site up and running quickly. The template incorporates accessibility standards to support high compliance with ADA best practices. You can install the template to a new site using the Square Online CLI. For steps, see Get Started.
Square Online CLI Tool used for creating a custom theme (with starter files) and managing site files from a local development environment. For more information, see Square Online CLI Reference.
Note: The CLI provides wrapper commands for the Sites API. The Sites API reference is provided for completeness, but we recommend that you use the CLI.
Square Online code editor Full-featured IDE available from the site editor in the Square Online dashboard. For more information, see Code Editor Overview.
Template Syntax Reference Documentation and examples for supported tags, filters, and functions that you can insert into .twig template files.
Bootstrapped Resources Reference Documentation for automatically bootstrapped resources available on the top-level square namespace that you can use in Square Online pages.
Resources Reference Documentation for catalog, cart, and other Square Online resources that you can use in Square Online pages.
Site Theme SDK Reference Documentation for client SDK that can be called from pages to perform dynamic site actions, such as fetching resources and managing the cart. The SDK is intended to simplify site actions and can be used instead of calling Client APIs directly. For more information, see Site Theme SDK Reference.
Client APIs Client APIs that can be called from pages to perform dynamic site actions, such as fetching resources and managing the cart. For more information, see Client APIs Reference.
FAQs Frequently asked questions about custom site development.
Changelog Record of notable changes to APIs, SDKs, and documentation.
Breaking Changes Details on any breaking changes.

Limitations

  • You can build a custom cart experience but you cannot customize the existing cart page or customize the checkout page. All orders made from custom sites must be processed using Square Online’s checkout.

  • During this Alpha phase, custom sites functionality is limited to sellers in the United States or Canada.

  • Square provides a starter template to help speed up the development process. The template is specialized for retail sites and isn’t applicable when developing sites for other verticals (such as Food & Beverage). The template files are installed when you run theme install in the Square Online CLI.

  • Creating custom editor controls (that enable sellers to update site code) isn’t currently supported.

  • Currently, not all core Square Online features can be integrated into custom sites or pages. For more information, see Supported Square Online features.

  • The Square Sandbox test environment isn’t supported.

  • Square webhook events aren’t supported.