Square Online

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.

How it works Permalink Get a link to this section

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 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 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 My call returns a RATE_LIMITED error code.

  • 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.

    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 Best Practices for the OAuth API.

Requirements and limitations Permalink Get a link to this section

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.

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

OAuth requirements Permalink Get a link to this section

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 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 Ensure tokens are valid.

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.

Subscribe to the token revoked event (recommended) Permalink Get a link to this section

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.

  1. In the Developer Dashboard, open your application.

    Note

    For information about signing up for a Square account and creating an application, see Get Started. Square Online must be available in the country that you select when you create your account.

  2. At the top of the page, choose Production. The Snippets API is not available in the Sandbox environment.

  3. In the navigation pane, choose Webhooks. Ignore the Enable Webhooks setting, which applies to webhooks for Connect v1 APIs.

  4. Choose Add Endpoint, and then configure the endpoint:

    1. For Webhook Name, enter a name such as Access Revoked.

    2. 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.

    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 more information, see Square Webhooks.

Note

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.

Security considerations Permalink Get a link to this section

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.site domain or on a custom domain, so the Square session cannot be accessed or hijacked.

Best practices Permalink Get a link to this section

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>, <link>, <meta>, <style>, and <title>. Do not include displayable HTML elements, such as <div>, <p>, or <span>.

    Important

    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:

    • 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.

  • 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.

Related topics Permalink Get a link to this section