Add a Snippet to a Site

Applications can use the Snippets API and Sites API to add a snippet to a Square Online site. Applications must provide a management dashboard that allows Square sellers to add and manage your snippet on their sites. For more information, see Snippets API Overview.

The following steps show a typical application flow for adding a snippet to a site:

1. Call ListSites to get a list of the seller's Square Online sites:

   Replace {ACCESS_TOKEN} with a valid access token. This token can be one of the following:

   • The personal access token for the production environment (not the Sandbox) that you copy from the Developer Dashboard. This token allows unrestricted access to the resources in your Square account.
   • An OAuth access token that you obtain through the OAuth authentication flow. This token allows scoped access to the resources in the Square account that granted permission.

   List sites

   cURL

   The following is an example ListSites response:

   {
     "sites": [
       {
         "id": "site_27807527648example",
         "site_title": "My Second Site",
         "domain": "mysite2.square.site",
         "is_published": true,
         "created_at": "2020-10-28T13:22:51.000000Z", 
         "updated_at": "2021-01-13T09:58:32.000000Z" 
       },
       {
         "id": "site_10272534583example",
         "site_title": "My First Site",
         "domain": "mysite1.square.site",
         "is_published": true,
         "created_at": "2020-06-18T17:45:13.000000Z", 
         "updated_at": "2020-11-23T02:19:10.000000Z"
       }
     ]
   }

   For more information about obtaining and using access tokens, see Access Tokens and Other Square Credentials.

2. If a seller has multiple sites, you must allow sellers to choose the sites where they want to add your snippet.

   You can use the site_title, domain, and other fields from the ListSites response to display the sites to the sellers so they can select the target site or sites. Then, use the id of the selected site as the site_id parameter in your Snippet API requests.

   If the seller has only one site, you can just use the id of the site without prompting the seller to select a site.

3. Allow the seller to configure the snippet as needed. For example, you might provide custom settings or allow sellers to choose the functionality they want to add to their site. Although an application can define only one snippet, you can build your snippet code dynamically per site and concatenate multiple HTML elements.

4. For each selected site, call UpsertSnippet to add your snippet.

   • Replace {ACCESS_TOKEN} with your access token.
   • Replace {{SITE_ID}} with the ID of the target site. You can get this value from the id field in the ListSites response.
   • Replace the example value in the content field with your snippet code, which can include valid HTML, CSS, and JavaScript. The string has a maximum length of 65,535 characters.

   The snippet in the following example request is a google-site-verification meta tag used to verify site ownership:

   Upsert snippet

   cURL
   Note

   To see another snippet example, check out the Square Online Store Snippets Example sample application, which lets you choose an emoji to use as the cursor on a site.

   The following is an example UpsertSnippet response:

   {
     "snippet": {
       "id": "snippet_5d178150-a6c0-11eb-a9f1-437e6example",
       "site_id": "site_27807527648example",
       "content": "<meta name=\"google-site-verification\" content=\"+nxGUDJ4QpAZ5l9Bsjdi102tLVC21AIh5d1Nl23908Vexample=\"/>",
       "created_at": "2021-03-11T25:40:09.000000Z", 
       "updated_at": "2021-03-11T25:40:09.000000Z"
     }
   }
   Note

   If you encounter issues when running cURL commands from a terminal window (such as valid snippet code that returns a BAD_REQUEST error or encoded HTML in the response), try using API Explorer, Postman, or another tool to send your requests.

5. Now that you added a snippet to the site, you can call RetrieveSnippet, UpsertSnippet, and DeleteSnippet as needed to retrieve, update, or delete the snippet.

   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.

• Use API Explorer to build and test more calls to the Snippets API and Sites API. API Explorer runs against the resources in your account and generates syntax that you can use for cURL commands and language-specific SDK requests. For more information, see API Explorer Overview.

  Note that the Sites API and Snippets API aren't supported in the Square Sandbox.

• Try out the Square Online Store Snippets Example. This Ruby sample shows what a snippet application might look like. The sample can run locally using Docker Compose.

• If you want to start building your own application using a Square SDK, install the SDK in your preferred language. Make sure to use the production environment for your Sites API and Snippets API requests.

Square doesn't provide a sandbox eCommerce environment for testing snippets or calls to the Sites API or Snippets API. Therefore, you must test snippets and API calls using a Square Online site in the production environment and an access token for production resources.

1. In the Seller Dashboard, choose Online in the left pane.

   • If you haven't created any sites, choose Get started.
   • If you want to create another site, choose Add site from your account menu in the upper right.

2. Follow the UI prompts to create and publish your site.

   For more information, see Get Started with Square Online and How to Start a Free Online Store from Your Square Account.

1. In the Developer Dashboard, open your application. If you don't have a Square account, you need to create one.

2. At the top of the page, in the Sandbox and Production toggle, choose Production.

3. On the Credentials page, under Production Access Token, choose Show, and then copy the token. The token grants full access to the resources in your account.

   Use your access token to test your calls to the Snippets API and Sites API from your management dashboard. After you call UpsertSnippet to add or update the snippet to your test site, you can test the snippet functionality from your site.

   Note

   To learn how to obtain an OAuth access token for other Square accounts that you can use in your API requests, see OAuth API Overview.

The Square App Marketplace can help Square sellers discover your application. When your application is ready, you can submit it for approval to the App Marketplace. For more information, see Publish your App to the App Marketplace.

• Snippets API Overview
• Use the Snippets API
• Square Online Store Snippets Example
• Video: Sandbox Sessions: Snippets API