Overview Authentication and permissions Making requests Retrieve basic site information

Idempotency-Key header Rate limits Responses & error handling Upgrade Changelog Glossary FAQ

Overview GET: Retrieve all inventory GET: Retrieve specific inventory POST: Adjust stock quantities

Overview POST: Create an order POST: Fulfill an order GET: Retrieve all orders GET: Retrieve a specific order

Overview About product attributes Managing attributes POST: Create a product POST: Create a product variant POST: Upload a product image GET: Retrieve all Store Pages GET: Retrieve all products GET: Retrieve specific products GET: Product image upload status POST: Assign a product image to variant POST: Reorder a product image POST: Update a product POST: Update a product variant POST: Update a product image DEL: Delete a product DEL: Delete a product variant DEL: Delete a product image

Overview GET: Retrieve all profiles GET: Retrieve specific profiles

Overview GET: Retrieve all transactions GET: Retrieve specific transactions

Overview POST: Create a webhook subscription POST: Update a webhook subscription GET: Retrieve all webhook subscriptions GET: Retrieve a specific webhook subscription DEL: Delete a webhook subscription POST: Send test notification POST: Rotate a subscription secret

Retrieve all products

GET https://api.squarespace.com/{api-version}/commerce/products?modifiedAfter={a-datetime}&modifiedBefore={b-datetime}&type={c}&cursor={d}

Retrieves information for all physical and/or download products; products can be filtered within a date range and by product type.

Caution: A request cannot use both a cursor and a date range; only a cursor OR a date range may be used.

The response contains product information in a Product, up to 50 Products ordered by their modification date (modifiedOn), and supports dynamic cursors for pagination. Read the Overview to learn more about Products.

Parameters

{api-version} string
required

See the Products API Overview page for the current API version. Documentation for earlier API versions for this endpoint can be found below.

1.0

modifiedAfter={a-datetime} string
conditional: required when modifiedBefore is passed, cannot be used with cursor

Time-boxes the request to Products that were modified after {a-datetime} where {a-datetime} is an ISO 8601 UTC date and time string, e.g. YYYY-MM-DDThh:mm:ss.sZ.

modifiedBefore={b-datetime} string
conditional: required when modifiedAfter is passed, cannot be used with cursor

Time-boxes the request to Products that were modified before {b-datetime} where {b-datetime} is an ISO 8601 UTC date and time string, e.g. YYYY-MM-DDThh:mm:ss.sZ.

type={c} string
conditional: cannot be used with cursor, required otherwise

Identifies the type(s) of products to retrieve. See the Products API Overview for an explanation of the various product types. {c} should be a comma-delimited list of product types. The currently supported product types are PHYSICAL and DIGITAL.

cursor={d} string
conditional: cannot be used with other parameters

Identifies where the next page of results should begin. {c} should be the value of pagination.nextPageCursor from a previous response. If this parameter is not present or empty, the endpoint returns up to 50 Products.

Request example

Read the Making requests guide to learn why specific headers are necessary, and why some are omitted. Every request should also abide by Squarespace rate limits.

curl "https://api.squarespace.com/1.1/commerce/products?cursor=abc" \
  -i \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"

Response example

A successful request generates a JSON response with an array of Products and a pagination object.

Note: For easier reference between response fields and descriptions, comments were added in the example, though this makes the JSON invalid.

{
  // Array of Product resources.
  // If the merchant site doesn't have any products, this array is empty.
  "products": [
    {
      // Unique Product id.
      "id": "5ed539b66505ca7c5f4a3a5a",
      // Product type indicator.
      // Value may be: `PHYSICAL` or `DIGITAL`.
      "type": "PHYSICAL",
      // Identifier of the product's Store Page.
      "storePageId": "5d7ba084a63ee8bb410ce0b1",
      // Product name.
      "name": "Artisanal Steak Dry Rub",
      // Long-form product description represented in HTML.
      "description": "<p>This can be a few words or even a few <i>paragraphs</i>.</p>",
      // Absolute URL of the product details page.
      "url": "https://example.com/store/artisanal-steak-dry-rub",
      // URL slug for the new product.
      "urlSlug": "artisanal-steak-dry-rub",
      // Keywords for search and organization purposes.
      "tags": ["artisanal", "steak"],
      // Indicates whether the product is available for purchase.
      "isVisible": true,
      // Options for search engine optimization.
      "seoOptions": {
        // Page title that appears in search results and browser tabs;
        // indexed by search engines.
        "title": "Artisanal Cooking",
        // Page description that appears below the title or link in search results.
        "description": "A one-stop shop for artisanal cooking tips and products."
      },
      // List of attributes to distinguish variants of the product.
      "variantAttributes": ["Flavor"],
      // List of variants of the product.
      "variants": [{
        // Unique ProductVariant id.
        "id": "6b76dad2-a15a-4dfc-97e1-47427e12061f",
        // Merchant-defined code that identifies the product variant.
        "sku": "SQ0557856",
        // Pricing data for the variant.
        "pricing": {
          // Amount per unit charged for the variant.
          "basePrice": {
            // ISO 4217 currency code string.
            "currency": "USD",
            // Monetary amount.
            "value": "12.95"
          },
          // Amount per unit charged when the variant is on sale.
          "salePrice": {
            // ISO 4217 currency code string.
            // If `onSale` is false; field defaults to the merchant site's currency setting.
            "currency": "USD",
            // Monetary amount.
            // If `onSale` is false, field coalesces to the lesser of this and `basePrice.value`.
            "value": "0.00"
          },
          // Indicates whether the variant is sold according to its sale price.
          "onSale": false
        },
        // Available stock for the variant.
        "stock": {
          // Number of units that can be purchased.
          "quantity": 10,
          // Indicates whether the variant has unlimited stock.
          "unlimited": false
        },
        // Specifies attribute-value pairs for the variant.
        "attributes": {
          "Flavor": "Habanero"
        },
        // Measurements of the variant when it's shipped.
        "shippingMeasurements": {
          // Weight of the variant.
          "weight": {
            // Unit of measurement.
            // Supported values: `KILOGRAM`, `POUND`.
            "unit": "POUND",
            // Weight amount.
            "value": 2.0
          },
          // Physical dimensions of the variant.
          "dimensions": {
            // Unit of measurement.
            // Supported values: `INCH`, `CENTIMETER`.
            "unit": "INCH",
            // Length of the variant.
            "length": 7.0,
            // Width of the variant.
            "width": 5.0,
            // Height of the variant.
            "height": 5.0
          }
        },
        // Product image assigned to the variant.
        "image": {
          "id": "5ed539bc8367410cdc0c984a",
          "title": "Steak",
          "url": "https://static1.squarespace.com/static/steak.png",
          "originalSize": {
            "width": 512,
            "height": 256
          },
          "availableFormats": ["100w", "300w", "500w"]
        }
      }],
      // List of product images.
      "images": [{
        // Unique ProductImage id.
        "id": "5ed539bc8367410cdc0c984a",
        // Alt text for the image; impacts SEO and appears in search results.
        "altText": "Steak",
        // Absolute URL of the image hosted on Squarespace.
        "url": "https://static1.squarespace.com/static/steak.png",
        // Image size when first uploaded.
        "originalSize": {
          // Width in pixels.
          "width": 512,
          // Height in pixels.
          "height": 256
        },
        // Available image sizes. Use with `images.url` and a `format` query parameter
        // to retrieve the image at a particular width.
        // E.g., https://static1.squarespace.com/static/steak.png?format=300w
        "availableFormats": ["100w", "300w", "500w"]
      }],
      // ISO 8601 UTC date and time string; represents when the Product was created.
      "createdOn": "2020-06-01T17:24:06.048Z",
      // ISO 8601 UTC date and time string; represents when the Product was last modified.
      "modifiedOn": "2020-06-04T20:12:18.163Z"
    },
    {
      // Unique Product id.
      "id": "5ff738b49506ca7c5g1b3c4a",
      // Product type indicator.
      // Value may be: `PHYSICAL` or `DIGITAL`.
      "type": "DIGITAL",
      // Identifier of the product's Store Page.
      "storePageId": "5d7ba084a63ee8bb410ce0b1",
      // Product name.
      "name": "The Artisan's Cookbook (eBook)",
      // Long-form product description represented in HTML.
      "description": "<p>This can be a few words or even a few <i>paragraphs</i>.</p>",
      // Absolute URL of the product details page.
      "url": "https://example.com/store/the-artisans-cookbok-ebook",
      // URL slug for the new product.
      "urlSlug": "the-artisans-cookbook-ebook",
      // Keywords for search and organization purposes.
      "tags": ["artisanal", "cookbook", "ebook"],
      // Indicates whether the product is available for purchase.
      "isVisible": true,
      // Options for search engine optimization.
      "seoOptions": {
        // Page title that appears in search results and browser tabs;
        // indexed by search engines.
        "title": "Artisanal Cooking",
        // Page description that appears below the title or link in search results.
        "description": "A one-stop shop for artisanal cooking tips and products."
      },
      // List of product images.
      "images": [{
        // Unique ProductImage id.
        "id": "60e359bd8467521dff3e993b",
        // Alt text for the image; impacts SEO and appears in search results.
        "altText": "Cover",
        // Absolute URL of the image hosted on Squarespace.
        "url": "https://static1.squarespace.com/static/cookbook-cover.png",
        // Image size when first uploaded.
        "originalSize": {
        // Width in pixels.
          "width": 512,
          // Height in pixels.
          "height": 256
        },
        // Available image sizes. Use with `images.url` and a `format` query parameter
        // to retrieve the image at a particular width.
        // E.g., https://static1.squarespace.com/static/cookbook-cover.png?format=300w
        "availableFormats": ["100w", "300w", "500w"]
      }],
      "pricing": {
        // Amount per unit charged for the variant.
        "basePrice": {
          // ISO 4217 currency code string.
          "currency": "USD",
          // Monetary amount.
          "value": "4.95"
        },
        // Amount per unit charged when the variant is on sale.
        "salePrice": {
          // ISO 4217 currency code string.
          // If `onSale` is false; field defaults to the merchant site's currency setting.
          "currency": "USD",
          // Monetary amount.
          // If `onSale` is false, field coalesces to the lesser of this and `basePrice.value`.
          "value": "2.95"
        },
        // Indicates whether the variant is sold according to its sale price.
        "onSale": true
      },
      "digitalGood": {
        // Unique DigitalGood id.
        "id": "643bc32ffb58f41fb9f611a8",
        // Filename of the downloadable file.
        "filename": "cookbook.pdf"
      },
      // ISO 8601 UTC date and time string; represents when the Product was created.
      "createdOn": "2020-07-02T18:33:46.657Z",
      // ISO 8601 UTC date and time string; represents when the Product was last modified.
      "modifiedOn": "2020-08-04T10:42:29.269Z"
    }
  ],
  // Provides pagination details for iterating on the Products
  // available from the merchant site.
  "pagination": {
    // Flag; indicates whether another page of data is available.
    "hasNextPage": true,
    // Cursor to use in a subsequent request; retrieves the next page of data.
    "nextPageCursor": "b342f5367c664d3c99aa56f44f95ab0a",
    // A pre-built URL for applications to request the next page of data.
    "nextPageUrl":
    "https://api.squarespace.com/1.0/commerce/products?cursor=NTA"
  }
}

Status codes and error conditions

200 OK

The request was successful. The message body contains data in the format specified above.

400 BAD REQUEST

Type: INVALID_REQUEST_ERROR

Subtype: null
The request contains one or more errors caused by any of the following:

The cursor parameter contains an invalid value.
cursor parameter was specified with other request parameters.
modifiedAfter or modifiedBefore was specified without the other parameter.
modifiedAfter is not a valid ISO 8601 UTC date and time string.
modifiedBefore is not a valid ISO 8601 UTC date and time string.
modifiedBefore occurred before or at the same time as modifiedAfter.