Snippets API

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.

Square Online APIs are publicly available as part of an early access program. For more information, see Early access program for Square Online APIs.

Add a snippet Permalink Get a link to this section

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

    curl -X GET \
     https://connect.squareup.com/v2/sites \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json'
    

    The following is an example ListSites response:

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

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

  1. 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 sites. After a seller chooses a site, use the corresponding id field as the site_id parameter in your Snippet API requests.

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

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

  1. Call UpsertSnippet to add your snippet to each selected site.

    • 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 must be a string that contains valid HTML, CSS, JavaScript, or a combination of the three. 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:

    curl -X POST \
      https://connect.squareup.com/v2/sites/{site_id}/snippet \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "snippet": {
          "content": "<meta name=\"google-site-verification\" content=\"+nxGUDJ4QpAZ5l9Bsjdi102tLVC21AIh5d1Nl23908Vexample=\"/>"
        }
      }'
    

    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:09Z", 
        "updated_at": "2021-03-11T25:40:09Z"
      }
    }
    

    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.

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

Next steps Permalink Get a link to this section

  • 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 Test Square APIs with API Explorer.

    Make sure to choose Production in the environment toggle at the top of the page. The Sites API or Snippets API are not supported in the Square Sandbox.

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

Test your application Permalink Get a link to this section

Square does not 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.

Square Online must be available in the country that you selected when you created the account.

To create a test site Permalink Get a link to this section

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

    • If you have not 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.

To get your Production access token Permalink Get a link to this section

  1. In the Developer Dashboard, open your application.

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

  1. On the Credentials page, under Personal 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 Authorizing an application and obtaining access tokens.

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 App Marketplace.

Related topics Permalink Get a link to this section