Add a Snippet to a Site

Applies to: Snippets APISnippets API | Sites APISites API

Learn how to use the Snippets API and Sites API to add a snippet to a Square Online 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 APISnippets API.

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

1. Call ListSitesListSites 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 Consolecopy from the Developer Console. This token allows unrestricted access to the resources in your Square account.
   • An OAuth access token that you obtain through the OAuth authentication flowOAuth authentication flow. This token allows scoped access to the resources in the Square account that granted permission.

   List sites

   cURL

   Copy

   The following is an example ListSites response:

   Copy

   Expand

   {
     "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 CredentialsAccess 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 UpsertSnippetUpsertSnippet 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-verificationgoogle-site-verification meta tag used to verify site ownership:

   Upsert snippet

   cURL

   Copy

   Note

   To see another snippet example, check out the Square Online Store Snippets ExampleSquare 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:

   Copy

   Expand

   {
     "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 ExplorerAPI Explorer, Postman, or another tool to send your requests.

5. Now that you added a snippet to the site, you can call RetrieveSnippetRetrieveSnippet, UpsertSnippetUpsertSnippet, and DeleteSnippetDeleteSnippet 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 PracticesOAuth Best Practices.

• Use API ExplorerAPI 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 ExplorerAPI Explorer.

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

• Try out the Square Online Store Snippets ExampleSquare 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 SDKSquare 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 Square DashboardSquare 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 OnlineGet Started with Square Online and How to Start a Free Online Store from Your Square AccountHow to Start a Free Online Store from Your Square Account.

1. In the Developer ConsoleDeveloper Console, 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 calling UpsertSnippet to add the snippet to your test site, you can test the snippet functionality from your site.

   Note

   To learn how to obtain an OAuth access tokenOAuth access tokenRepresents the set of permissions allowed by a seller. OAuth access tokens are obtained through an OAuth flow using your application credentials. that you can use in API requests to access resources in other Square accounts, see OAuth APIOAuth API.

The Square App MarketplaceSquare 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 MarketplacePublish your App to the App Marketplace.

• Snippets APISnippets API
• Use the Snippets APIUse the Snippets API
• Square Online Store Snippets ExampleSquare Online Store Snippets Example
• Video: Sandbox Sessions: Snippets APIVideo: Sandbox Sessions: Snippets API