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.
Square Online APIs are publicly available as part of an early access program. For more information, see Early access program for Square Online APIs.
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.
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:
contentfield of a Snippet object, as shown in the following example request body:
An application can have only one snippet on a given site at a time.
Snippets are not 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
UpsertSnippetto update the snippet as needed.
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. 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 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.
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 Best Practices for the OAuth API.
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 is not supported. A snippet is injected at the end of the
<head>element on all pages on a site, except checkout pages. You should not 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 does not provide a sandbox eCommerce environment for testing snippets or calls to the Sites or Snippets API. For more information, see Testing your application.
For best practices and additional requirements for snippets and applications that integrate with the Snippets API, see Best practices.
Applications that use OAuth require the following OAuth permissions to access and manage site and snippet resources for a Square seller account:
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 Overview.
A snippet is tied to a particular application through the
client_id parameter provided in the OAuth flow.
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 Best Practices for the OAuth API.
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.
At the top of the page, choose Production. The Snippets API is not available in the Sandbox environment.
In the left pane, expand Webhooks, and then choose Subscriptions. Ignore the V1 Webhooks and Enable Webhooks sections, which apply to webhooks for deprecated Connect V1 APIs.
Choose Add subscription, and then configure the subscription:
For Webhook name, enter a name such as Access Revoked.
For URL, enter the URL of your listener. If you do not have a working URL yet, you can enter https://example.com as a placeholder.
Optional. For API version, choose a Square API version. By default, this is set to the same version as the application.
For Events, choose oauth.authorization.revoked.
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.
Square does not 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.
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 is not 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 should not attempt to integrate with any part of the checkout flow on a Square Online site.
Session cookie is protected
Cookies are stored on the
.square.sitedomain or on a custom domain, so the Square session cannot be accessed or hijacked.
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.
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
<title>. Do not include displayable HTML elements, such as
Although your snippet can manipulate the DOM, it should not 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.
Do not 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:
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.
Do not ask Square customers for a password. Your snippet should not 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.
Do not call Square APIs directly from the browser. Browsers do not 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.