Square Dashboard Add-Ons Developer Preview Documentation

Seamlessly integrate your application with Square Dashboard.

Square Dashboard Add-ons give sellers the ability to interact with your application directly from Square Dashboard, so they have a more complete view of their business, and can complete common workflows with minimal context switching. For example, sellers can access data or insights from your application directly in the Square Dashboard home page, or can complete simple workflows without needing to sign-in or navigate to your app.

Screenshot of the home widgets placement in the Square Seller Dashboard

The functionality described in this documentation is currently in private alpha. Functionality is released in alpha to give developers an opportunity to preview the intended release and provide feedback. Changes to the described functionality (including breaking changes) are possible between alpha and a public beta release.

Throughout the documentation, “Dashboard” refers to Square Dashboard, which is the web-based admin interface sellers use to mange their business on Square.

How Dashboard Add-ons Work

Dashboard Add-ons are front-end extensions of your application that are rendered inside the document context of the Dashboard. Add-ons receive context about the page that they’re loaded on, and provide functionality to sellers through the use of provided UI components. Dashboard Add-ons also support calling your own self-hosted back-end.

Square provides a set of locations where an Add-on can appear in the Dashboard UI. For the Developer Preview release, these locations are the Square Dashboard Home page, the Items and Customer pages where the Add-on first appears as a card component. From the card component initial entry point, you can extend the Add-on into a full side-bar blade or modal to display additional data or provide additional user interaction.

The following pages are places where you can run Square Dashboard Add-ons:

  • Dashboard Home Widgets
  • Items Details
  • Customer Details

Additional pages will be supported in future releases.

Component context

When Dashboard loads an Add-on, the Dashboard provides the Add-on with relevant context about where the UI web component is being rendered. For example, for the Customer Details page, the Dashboard provides the Customer ID to the Add-on for context.

Hosting

The front-end component of an Add-on is hosted by Square. Developers will need to package and submit each new version of the Add-On to Square before the Add-on can be published or installed.

UI components

Square provides a React component library that ensures a consistent experience with Dashboard. For more information, see the UI Component Reference.

Calling Square APIs

Dashboard Add-ons can call Square APIs through their own third-party back-end, when the parent application has requested the required permissions and that the seller granted access via OAuth. A seller goes through the Square OAuth flow when connecting to an application that includes an Add-on, and these permissions are inherited by the Add-on.

For authentication, Dashboard Add-ons uses JWT (JSON Web Tokens) credentials. When you make a request to your application’s back-end, Square inserts an authorization header in the form of a signed JWT token that encodes information about the signed-in seller. For more information, see the Back-end Authentication Guide.

Private installing an Add-on

With the Square Dashboard Add-ons CLI, you can privately install a version of an add-on to your own Square account. You can test your Add-on in the Dashboard without other sellers interacting with it.