Applies to: Snippets API | Sites API
Learn how applications can integrate with the Snippets API to add custom functionality to Square Online sites.
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.
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:
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.
- 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.
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 Square 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:
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.
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.
If a seller disconnects your application from the Square 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 Console, 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:
- 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 in a timely manner. For general information about webhooks, see Square Webhooks. 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.
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.