Snippets API

Use the Snippets API

You can use the Snippets API to manage a snippet on a Square Online site. Snippets add custom functionality to Square Online 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 or update a snippet
Retrieve a snippet
Delete a snippet
Related topics

Link to section
Add or update a snippet

The UpsertSnippet endpoint adds or updates a snippet on a Square Online site. This operation appends the snippet code to the end of the head tag on every page of the site, except for checkout pages. Snippet code is sent as a string that contains valid HTML, CSS, JavaScript, or a combination of the three. The string has a maximum length of 65,535 characters.

An application can create and manage one snippet on any given site. For an example workflow, see Add a Snippet to a Site.

The following is an example request. To get the site ID, call the ListSites endpoint to retrieve the sites that belong to a seller.

Upsert Snippet

1
2
3
4
5
6
7
8
9
10

curl https://connect.squareup.com/v2/sites/{{SITE_ID}}/snippet \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "snippet": {
      "content": "<script type=\"text/javascript\">var js = 1;</script>"
    }
  }'

If successful, this endpoint returns a 200 OK status code and a response similar to the following example:

{
  "snippet": {
    "id": "snippet_5d178150-a6c0-11eb-a9f1-437e6example",
    "site_id": "site_27807527648example",
    "content": "<script type=\"text/javascript\">var js = 1;</script>",
    "created_at": "2021-03-11T25:40:09.000000Z", 
    "updated_at": "2021-03-11T25:40:09.000000Z"
  }
}

The snippet ID is not required for requests to the Snippets API because an application can add only one snippet to a site.

If the site cannot be found, this endpoint returns a 404 Not Found status code and the following response:

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "NOT_FOUND",
      "detail": "Resource not found."
    }
  ]
}

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.

Link to section
Retrieve a snippet

The RetrieveSnippet endpoint retrieves a snippet from a Square Online site. A site can contain snippets from multiple applications, but you can retrieve only the snippet that was added by your application.

The following is an example request. To get the site ID, call the ListSites endpoint to retrieve the sites that belong to a seller.

Retrieve Snippet

curl https://connect.squareup.com/v2/sites/{{SITE_ID}}/snippet \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

If successful, this endpoint returns a 200 OK status code and a response similar to the following example:

{
  "snippet": {
    "id": "snippet_5d178150-a6c0-11eb-a9f1-437e6example",
    "site_id": "site_27807527648example",
    "content": "<script type=\"text/javascript\">var js = 1;</script>",
    "created_at": "2021-03-11T25:40:09.000000Z", 
    "updated_at": "2021-03-11T25:40:09.000000Z"
  }
}

If the snippet cannot be found, this endpoint returns a 404 Not Found status code and the following response:

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "NOT_FOUND",
      "detail": "Resource not found."
    }
  ]
}

Link to section
Delete a snippet

The DeleteSnippet endpoint removes a snippet from a Square Online site. You can delete only the snippet that was added by your application.

The following is an example request. To get the site ID, call the ListSites endpoint to retrieve the sites that belong to a seller.

Delete Snippet

curl https://connect.squareup.com/v2/sites/{{SITE_ID}}/snippet \
  -X DELETE \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

If successful, this endpoint returns a 200 OK status code and an empty JSON object:

{}

If there is no snippet for the specified site, this endpoint returns a 404 Not Found status code and the following response:

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "NOT_FOUND",
      "detail": "Resource not found."
    }
  ]
}

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Use the Snippets API

On this page

Link to section
Add or update a snippet

Note

Note

Link to section
Retrieve a snippet

Link to section
Delete a snippet

Link to section
Related topics

On this page

Docs

Use the Snippets API

On this page

Link to section Add or update a snippet

Note

Note

Link to section Retrieve a snippet

Link to section Delete a snippet

Link to section Related topics

On this page

Link to section
Add or update a snippet

Link to section
Retrieve a snippet

Link to section
Delete a snippet

Link to section
Related topics