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.
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 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
UpsertSnippetto update the snippet as needed.
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.
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.
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 API Overview.
A snippet is tied to a particular application through the
client_id parameter provided in the OAuth flow.
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 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:
- For Webhook name, enter a name such as Access Revoked.
- 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.
- 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.
- 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.
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.sitedomain or on a custom domain, so the Square session cannot be accessed or hijacked.