Snippets API Overview

Square sellers use Square Online to build eCommerce websites with a rich set of features. Sellers can also add custom functionality to their sites through third-party applications. You can use the Snippets API to create applications that help sellers streamline business operations and create a better online experience.

Note

Square Online APIs are publicly available as part of an early access program. For more information, see Early access program for Square Online APIs.

How it works

Applications can use the Snippets API to add a snippet to a Square Online site. Snippets are scripts that can run as various site components (such as modals, pop ups, or background jobs) and offer a range of functionality. For example, a snippet can integrate with Square and external products or services, improve customer acquisition and engagement, and provide industry-specific or general tools that help businesses run more efficiently. For more integration ideas, see Introducing Snippets API.

A graphic showing that snippets can run as various site components and provide a range of functionality.

When a seller decides to add your snippet to their site, they connect their Square account to your application. The seller is then redirected to your application, where they can configure preferences, options, or any other details your application needs to generate your snippet.

When the snippet is ready, your application calls the Snippets API to add the snippet to the target site. This operation injects the snippet at the end of the <head> element on all pages of the site, except for checkout pages.

A snippet application includes the following components:

Snippet code - A string that can contain valid HTML, CSS, and JavaScript. The code is sent to the Snippets API in the content field of a Snippet object, as shown in the following example request body:
```
{
  "snippet": {
    "content": "{YOUR SNIPPET CODE HERE}"
  }
}
```
An application can have only one snippet on a given site at a time.
Although the snippet is limited to a single string, it can contain multiple HTML elements and reference external JavaScript libraries. In addition, you can build the snippet dynamically per site before sending it to the Snippets API.
Snippets aren't intended to interact directly with Square APIs. To integrate with orders, customers, or other Square features, your application can call Square APIs and then call UpsertSnippet to update the snippet as needed.
Note
If your application sends a high number of calls to Square APIs in a short period of time, you should make sure to handle potential rate limiting errors. For more information, see RATE_LIMIT_ERROR.
Management dashboard - The UI on a developer-hosted site that allows sellers to manage your snippet on their Square Online sites. Your dashboard must enable sellers to:
- Sign in with their Square account. For information about using the OAuth API to obtain an access token, see OAuth API Overview.
- Add or remove your snippet from Square Online sites. Sellers who have multiple sites must be able to choose the target site or sites.
Depending on your workflows, your dashboard calls the Snippets and Sites APIs to perform the following tasks:
Applications can only access their own snippet for a given site; they cannot access snippets created by other applications.
Note
Square also requires that your application allows sellers to view the status of their Square OAuth access token and to disconnect your application by revoking the access token. For more information, see OAuth Best Practices.

Link to section

Requirements and limitations

You should be aware of the following requirements, limitations, and other considerations when working with snippets and the Snippets API:

Snippets can be added to Square Online sites only.
Integration with the checkout flow isn't supported. A snippet is injected at the end of the <head> element on all pages on a site, except checkout pages. You shouldn't attempt to integrate with any part of the checkout flow on a Square Online site.
An application can add one snippet per site. A site can contain snippets from multiple applications, but only one snippet from a given application.
You must disclose information to the seller about your snippet, such as how to use the snippet, the information that it collects, and how to enable or disable it.
Sellers cannot view or edit your snippet code from the Seller Dashboard.
If a seller disconnects your application or revokes its permissions, Square removes your snippet from the site. For more information, see Subscribe to the token revoked event.
Square doesn't provide a sandbox eCommerce environment for testing snippets or calls to the Sites or Snippets API. For more information, see Test your application.

For best practices and additional requirements for snippets and applications that integrate with the Snippets API, see Best practices.

Link to section

OAuth requirements

Applications that use OAuth require the following OAuth permissions to access and manage site and snippet resources for a Square seller account:

ONLINE_STORE_SITE_READ
ONLINE_STORE_SNIPPETS_READ
ONLINE_STORE_SNIPPETS_WRITE

Your application uses these permissions to call the Snippets and Sites APIs on behalf of a seller. Depending on its functionality, your application might also require other Square permissions. For more information, see OAuth API Overview.

A snippet is tied to a particular application through the client_id parameter provided in the OAuth flow.

Important

Make sure to periodically refresh your OAuth tokens. This is especially important when your application calls other Square APIs. If a token expires, your calls to Square APIs will fail. For more information, see Refresh the access token.

You must follow best practices for obtaining and handling customer data and OAuth access tokens. For more information, see Best Practices for Collecting Information and OAuth Best Practices.

Link to section

Subscribe to the token revoked event (recommended)

If a seller disconnects your application from the Seller Dashboard, Square revokes the OAuth permissions for your application and triggers the oauth.authorization.revoked webhook event. Square listens for this event and then removes your snippet code from the seller's site.

If you store customer data or OAuth access tokens for sellers, you should also subscribe to this event. Then, you can use the merchant_id field in the event notification to find and delete any information you stored for the seller.

In the Developer Dashboard, open your application.
Note
For information about signing up for a Square account and creating an application, see Get Started.
At the top of the page, choose Production. The Snippets API isn't available in the Sandbox environment.
In the left pane, expand Webhooks, and then choose Subscriptions.
Choose Add subscription, and then configure the subscription:
1. For Webhook name, enter a name such as Access Revoked.
2. For URL, enter the URL of your listener. If you don't have a working URL yet, you can enter https://example.com as a placeholder.
3. Optional. For API version, choose a Square API version. By default, this is set to the same version as the application.
4. For Events, choose oauth.authorization.revoked.
5. Choose Save.

Your listener must validate the notification and respond with an HTTP 2xx response code within 10 seconds. For general information about webhooks, see Square Webhooks Overview. For information about viewing webhook logs, see Webhook Event Logs.

Note

Square doesn't send webhook notifications for snippet events because a snippet can be accessed only by the application that added it to the site. It cannot be accessed by the seller or other applications.

Link to section

Security considerations

You should be aware of the following security considerations when working with snippets and the Snippets API:

Snippets integration must be approved for Square App Marketplace - Applications that integrate with the Snippets API must receive explicit approval from Square before they can be listed in the Square App Marketplace. Snippet applications that are submitted for approval are subject to a stringent review and vetting process.
Integration with the checkout flow isn't supported - Snippets are injected at the end of the <head> element on all pages of the site, except for checkout pages. This reduces the risk that a snippet can access sensitive customer or payment information. You shouldn't attempt to integrate with any part of the checkout flow on a Square Online site.
The session cookie is protected - Cookies are stored on the .square.site domain or on a custom domain, so the Square session cannot be accessed or hijacked.

Link to section

Best practices

The following best practices and additional requirements apply when working with snippets:

Avoid blocking code in your snippet - Snippets are inserted into the <head> element of site pages, so you should avoid any code that might cause pages to load slowly or prevent the rest of the page from loading.
You can have your snippet code execute after the Document Object Model (DOM) is loaded. Many JavaScript libraries have this functionality built in.
Use CDNs to load remote assets - When possible, your snippet should use content delivery networks (CDNs) to load remote assets (using the HTTPS and TLS protocols). Also when possible, the assets should be loaded asynchronously.
Use appropriate HTML elements - Your snippet should include only HTML elements that are permitted in the <head> element, such as <script>, *, <meta>, <style>, and <title>. Don't include displayable HTML elements, such as , , or ``.
Important
Although your snippet can manipulate the DOM, it shouldn't rely on class names for DOM nodes or other HTML elements on Square Online pages. These names are subject to change without notice, so snippets that target specific DOM elements on the page might break at any time.
Don't use iFrames - Different browsers use different security protocols for iFrames, which can lead to inconsistent behavior across browsers for iFrames and snippets that use them.
Avoid behavior that results in a poor buyer experience - The snippet must not:
- Display ads, JavaScript alerts, confirmation boxes, or other distracting items.
- Expose unfriendly text to site users, such as overly technical error messages. All messages displayed to site users must be user friendly.
- Obscure any major element on a site without providing easy recourse.
- Excessively log debug or error messages to the JavaScript console.
Don't ask Square customers for a password - Your snippet shouldn't prompt customers to provide a password in the browser. If your implementation has a use case that requires obtaining a password from a customer in the browser, you should redirect the customer to your log in page or open a separate window to allow the customer to log in.
Don't call Square APIs directly from the browser - Browsers don't provide a secure environment for storing OAuth access tokens, application secrets, or other sensitive information.
Test on multiple device types - You must test your snippet to ensure that it functions properly on various device types, including desktop, mobile, and tablet.
Enable sellers to manage your snippet - Your application must provide a UI that enables sellers to:
- View a list of their Square Online sites and select which site or sites they want to add the snippet to.
- Check the status of the snippets on their site. For example, sellers should be able to see which sites the snippet is added to and whether the snippet is activated or deactivated.
- Remove the snippet from one or more sites.

Link to section

Docs

Snippets API Overview

Note

On this page

How it works

Note

Note

Requirements and limitations

OAuth requirements

Important

Subscribe to the token revoked event (recommended)

Note

Note

Security considerations

Best practices

Important

See also

On this page