### Start Server with Authentication

Source: https://developers.squarespace.com/local-development

Command to start the Squarespace Local Development Server with authentication, required for trial sites or sites with passwords.

```shell
squarespace-server https://site-name.squarespace.com --auth
```

--------------------------------

### Start Squarespace Development Server

Source: https://developers.squarespace.com/local-development

Command to start the Squarespace Local Development Server. Connects to the specified Squarespace site and runs on a local port.

```shell
squarespace-server https://site-name.squarespace.com
```

--------------------------------

### Install Squarespace Server via NPM

Source: https://developers.squarespace.com/local-development

Command to install the Squarespace Local Development Server globally using NPM. Requires Node.js and NPM to be installed beforehand.

```shell
npm install -g @squarespace/server
```

--------------------------------

### Example Template Configuration File (template.conf)

Source: https://developers.squarespace.com/template-configuration

This JSON file defines essential template metadata including name, author, site layouts with regions, navigation menus, and the order of stylesheet compilation.

```json
{
  "name" : "Template Name",
  "author" : "Author Name",

  "layouts" : {
    "default" : {
      "name" : "Default",
      "regions" : [ "site" ]
    }
  },

  "navigations" : [ {
      "title" : "Main Navigation",
      "name" : "mainNav"
  }, {
      "title" : "Secondary Navigation",
      "name" : "secondaryNav"
  } ],

  "stylesheets" : [ "global.less", "typography.less" ]
}
```

--------------------------------

### Example Request to Retrieve Products (Products API)

Source: https://developers.squarespace.com/commerce-apis/retrieve-all-products

This example demonstrates how to make a request to the Products API to retrieve products using a cursor for pagination. It includes necessary headers such as Authorization and User-Agent. Ensure you replace placeholders with your actual API key or token and a custom app description.

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

--------------------------------

### View Squarespace Server Help

Source: https://developers.squarespace.com/local-development

Command to display all available options and flags for the Squarespace Local Development Server.

```shell
squarespace-server --help
```

--------------------------------

### Retrieve All Store Pages - cURL Example

Source: https://developers.squarespace.com/commerce-apis/retrieve-all-store-pages

Example of how to make a request to retrieve all store pages using cURL. It demonstrates setting necessary headers like Authorization and User-Agent.

```cURL
curl "https://api.squarespace.com/{api-version}/commerce/store_pages" \
  -i \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
```

--------------------------------

### Configure navigation in template.conf

Source: https://developers.squarespace.com/beginner-tutorial

Defines navigation sections available in Squarespace interface. This example creates a 'Main Navigation' area for pages. Requires template.conf file in project root.

```JSON
{
  "name" : "Developer Platform Beginner Tutorial",
  "author" : "Squarespace",
  "navigations" : [
  {
    "title" : "Main Navigation",
    "name" : "mainNav"
  }],
  "layouts" : {
    "default" : {
      "name" : "Default",
      "regions" : [ "site" ]
    }
  },
  "stylesheets": []
}
```

--------------------------------

### Webhook Subscription Response Example (JSON)

Source: https://developers.squarespace.com/commerce-apis/retrieve-specific-webhook-subscription

Example JSON response for a successful request to retrieve a webhook subscription. It contains the subscription's ID, endpoint URL, subscribed topics, and timestamps for creation and updates.

```json
{
  "id": "7aff04bb-90e0-4002-96c2-69d8162c8dae",
  "endpointUrl": "https://example-extension.com/uninstall",
  "topics": ["extension.uninstall"],
  "createdOn": "2020-04-22T22:18+00:00",
  "updatedOn": "2020-04-22T22:18+00:00"
}
```

--------------------------------

### Products API - Overview and v2 Beta

Source: https://developers.squarespace.com/commerce-apis/changelog

Overview of the Products API, including details on product attributes, and information about the new v2 beta with enhanced product type support.

```APIDOC
## Products API - Overview and v2 Beta

### Description
This section provides an overview of the Products API, covering how to manage product attributes and introduces the beta version 2 (v2) of the Products API. V2 offers enhanced support for various product types including physical, service, gift card, and download products.

### Method
N/A (Overview)

### Endpoint
- v1 endpoints: `/commerce/products/*`
- v2 endpoints (Beta): `/v2/commerce/products/*`

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### Key Updates
- **v2 Beta**: Introduced with enhanced product type support (physical, service, gift card, download).
- **Attribute Limit**: Increased from three to six attributes per product.
- **Sale Prices**: `variants.salePrice.value` is now correctly set based on regular and sale prices.
- **Download Products (Read-only)**: Accessible via `retrieve all products` and `retrieve specific products` endpoints with a new `type` query parameter.
```

--------------------------------

### Retrieve Specific Profiles - cURL Example

Source: https://developers.squarespace.com/commerce-apis/retrieve-specific-profiles

Example cURL request to retrieve specific profiles from the Squarespace API. It includes necessary headers such as Authorization and User-Agent. Ensure to replace placeholders with your actual API key/token and application description.

```bash
curl "https://api.squarespace.com/1.0/profiles/5fc7b8f18b4dc33dc818aeba,5ede64464561317766bdc632" \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
```

--------------------------------

### Retrieve Specific Order - Curl Request Example

Source: https://developers.squarespace.com/commerce-apis/retrieve-specific-order

This example demonstrates how to retrieve a specific order using `curl`. It requires an `Authorization` header with an API key or OAuth token and a `User-Agent` header. Ensure you adhere to Squarespace's rate limits.

```bash
curl "https://api.squarespace.com/1.0/commerce/orders/123" \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
```

--------------------------------

### Create Blog List Template (HTML/JSON-T)

Source: https://developers.squarespace.com/beginner-tutorial

Defines the markup for the blog list page using Squarespace's JSON‑T templating language. It iterates over items, renders titles with conditional links, and shows excerpts or full body content. The template is saved as blog.list and works with the collection defined earlier.

```HTML
{.repeated section items}

  <!--WRAPPER-->

  <article id="post-{id}" class="{@|item-classes}" data-item-id="{id}

    <!--POST TILE-->

    <h1 class="title" data-content-field="title">
      {.passthrough?}
        <a href="{sourceUrl}" target="_blank">{title}</a>
      {.or}
        <a href="{fullUrl}">{title}</a>
      {.end}
    </h1>

    <!--EXCERPT OR BODY-->

    {.if excerpt}
      {excerpt}
      <a class="link" href="{fullUrl}">Read More</a>
    {.or}

    <!--MAIN CONTENT-->
      {body}

    {.end}

  </article>

{.or}
  No blog posts yet.
{.end}
```

--------------------------------

### POST: Create a product

Source: https://developers.squarespace.com/commerce-apis/glossary

Creates a new product in the Squarespace Commerce system. Supports various product types including physical goods, services, and digital downloads.

```APIDOC
## POST /products

### Description
Creates a new product in the Squarespace Commerce system. Supports physical goods, services, digital downloads, and other product types.

### Method
POST

### Endpoint
/products

### Request Body
- **name** (string) - Required - Product name
- **type** (string) - Required - Product type ("physical", "service", "digital", etc.)
- **description** (string) - Optional - Product description
- **variants** (array) - Optional - List of product variants
  - **name** (string) - Required - Variant name
  - **sku** (string) - Optional - Stock keeping unit
  - **price** (number) - Required - Variant price

### Request Example
{
  "name": "Key Lime Pie",
  "type": "physical",
  "description": "Delicious key lime pie with graham cracker crust",
  "variants": [
    {
      "name": "Standard",
      "sku": "PIE-KEYLIME",
      "price": 24.99
    }
  ]
}

### Response
#### Success Response (201)
- **productId** (string) - Created product ID
- **variants** (array) - List of created variant IDs

#### Response Example
{
  "productId": "PROD-123",
  "variants": ["VAR-456"]
}
```

--------------------------------

### GET /inventory

Source: https://developers.squarespace.com/commerce-apis/inventory-overview

Retrieve all inventory items for a Squarespace merchant site.

```APIDOC
## GET /inventory

### Description
Retrieve all inventory items for a Squarespace merchant site.

### Method
GET

### Endpoint
`/inventory`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Response
#### Success Response (200)
- **inventoryItems** (array) - A list of `InventoryItem` objects.
  - **variantId** (string) - The ID of the product variant.
  - **sku** (string) - The stock keeping unit (SKU) code.
  - **availability** (string) - The availability status ('in_stock', 'out_of_stock', 'unlimited').
  - **quantity** (integer) - The current stock quantity.

#### Response Example
```json
{
  "inventoryItems": [
    {
      "variantId": "variant_123",
      "sku": "TSHIRT-RED-L",
      "availability": "in_stock",
      "quantity": 50
    },
    {
      "variantId": "variant_456",
      "sku": "MUG-BLUE",
      "availability": "unlimited"
    }
  ]
}
```
```

--------------------------------

### Provide example Squarespace Products API response in JSON

Source: https://developers.squarespace.com/commerce-apis/retrieve-all-products

Shows the JSON payload returned by a successful Products API call, including product metadata, variant details, pricing, stock, and image information. Useful for developers integrating with Squarespace commerce endpoints; comments illustrate each field but must be removed for valid JSON.

```JSON
{
  // 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`, `SERVICE`, `GIFT_CARD`, 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 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.
      // Present for PHYSICAL and SERVICE products only.
      "variantAttributes": ["Flavor"],
      // List of variants of the product.
      // Present for PHYSICAL, SERVICE, and GIFT_CARD products only.
      "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.
          // Present for PHYSICAL and SERVICE products only.
          "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.
          // Present for PHYSICAL and SERVICE products only.
          "onSale": false
        },
        // Available stock for the variant.
        // Present for PHYSICAL and SERVICE products only.
        "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.
        // Present for PHYSICAL and SERVICE products only.
        "attributes": {
          "Flavor": "Habanero"
        },
        // Measurements of the variant when it's shipped.
        // Present for PHYSICAL products only.
        "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"

```

--------------------------------

### Generate Order JSON response example (JSON)

Source: https://developers.squarespace.com/commerce-apis/create-order

Shows the full JSON payload returned after creating an Order via the Squarespace Commerce API. It contains order metadata, customer information, line items with product details, shipping, and discount sections. The example includes inline comments for clarification, so it is not valid JSON for parsing.

```JSON
{
  // Unique Order id.
  "id" : "585d498fdee9f31a60284a37",
  // Unique, sequential number for the Order.
  "orderNumber" : "3",
  // ISO 8601 UTC date and time string; represents the moment when the order was placed.
  "createdOn" : "2017-01-25T17:13:26.205Z",
  // ISO 8601 UTC date and time string; represents when the order was last modified.
  "modifiedOn" : "2019-12-24T16:59:12.227Z",
  // Where the order originated; possible values are: `web` and `pos`.
  "channel": "web",
  // If `true`, the order is a test order created using a payment method in test mode.
  "mode" : true,
  // Email address entered at checkout or, for recurring subscription
  // orders, the customer's current email address.
  "customerEmail" : "john@example.com",
  // Customer's billing address.
  "billingAddress" : {
    "firstName" : "John",
    "lastName" : "Doe",
    "address1" : "8 Clarkson Street",
    "address2" : "Unit 2F",
    "city" : "New York",
    "state" : "NY",
    "countryCode" : "US",
    "postalCode" : "10004",
    "phone": "999-999-9999"
  },
  // Customer's shipping address provided at checkout or, for recurring subscription
  // orders, the customer's current mailing address.
  "shippingAddress" : {
    "firstName" : "Jane",
    "lastName" : "Smith",
    "address1" : "255 Varick Street",
    "address2" : "12th Floor",
    "city" : "New York",
    "state" : "NY",
    "countryCode" : "US",
    "postalCode" : "10003",
    "phone": "999-999-9999"
  },
  // Current fulfillment status of the order.
  // Value may be: `PENDING`, `FULFILLED`, or `CANCELED`.
  "fulfillmentStatusn  // Array of purchased line items; line items describe what product
  // or product variant was purchased, how many of that item
  // were purchased, and additional details.
  "lineItems" : [ {
    // Unique line item id.
    "id" : "585d4975dee9f31a60284a16",
    // Unique id of the ProductVariant sold.
    // See the Products API for information about ProductVariants.
    // This field is populated when these conditions are true:
    //  * The line item is a physical product variant, a service product variant, or a gift card.
    //  * The Order was created on or after May 28, 2019.
    "variantId": "AF705384-7641-4E8E-9F0A-C7E43BF88AB",
    // Stock keeping unit (SKU) code assigned by the Squarespace
    // merchant for a variant; used to identify an exact variant
    // of a product using a naming scheme preferred by the merchant.
    // Field is `null` for digital products.
    "sku" : "SQ3381024",
    // Unique product id; unless `null`, every line item with a
    // `variantId` is a variant of a product with `productId`.
    "productId" : "565c8f3da7c8a3cf71d5fd0a",
    // Name of the purchased product.
    "productName" : "Product",
    // Amount of the item purchased.
    "quantity" : 99,
    // Price the customer paid per unit of the item.
    "unitPricePaid" : {
      // ISO 4217 currency code string.
      "value" : "12.99",
      // Monetary amount with 1,000,000 limit and no markers for the dollar amount.
      // Conforms to the selected ISO currency's precision.
      // (E.g., JPY uses 123, but USD uses 123.00 or 123.)
      "currency" : "USD"
    },    // Array of variant options; represents variant choices made by
    // the customer, such as the size and color of a t-shirt.
    // Field is `null` for download and gift card products.
    "variantOptions" : [ {
      "value" : "Large",
      "optionName" : "Sizen    }, {
      "value" : "Black",
      "optionName" : "Color"
    } ],
    // Array of form data submitted via a product's custom form
    // prior to being added to the cart.
    "customizations": [ {
      "label": "Shirt Emblem Location",
      "value": "Middle Chest"
    } ],
    // URL of the primary image for the item.
    "imageUrl" : "https://static.squarespace.com/universal/commerce/images/brine-32oz-spring-mix-v2.jpg?format=300w",
    // Product type of the item.
    "lineItemType": "PHYSICAL_PRODUCT"
  },
  {
     "id": "5f05e2c7e3ed334d86ef8733",
     "variantId": null,
     "sku": null,
     "productId": "dc9c8f03-5a06-4c56-a03c-81a3a2d1682b",
     "productName": "Gift Wrapping",
     "quantity": 1,
     "unitPricePaid": {
       "currency": "USD",
       "value": "4.00"
     },
     "variantOptions": null,
     "customizations": null,
     "imageUrl": null,
     "lineItemType": "CUSTOM"
  }],
  // Array of shipping line items; describes the
  // shipping options chosen at checkout.
  "shippingLines" : [ {
    "method" : "Flat Rate",
    "amount" : {
      "value" : "5.99",
      "currency" : "USD"
    }
  } ],
  // Array of discount line items; describes the promotions
  // redeemed during checkout.
  "discountLines" : [ {

```

--------------------------------

### GET /webhooks/subscriptions

Source: https://developers.squarespace.com/commerce-apis/webhook-subscriptions-overview

Retrieves a list of all configured webhook subscriptions for the authenticated account.

```APIDOC
## GET /webhooks/subscriptions

### Description
Retrieves a list of all webhook subscriptions.

### Method
GET

### Endpoint
`/webhooks/subscriptions`

### Response
#### Success Response (200 OK)
- **subscriptions** (array of objects) - A list of webhook subscription objects.
  - **subscription_id** (string) - The unique identifier for the webhook subscription.
  - **endpoint** (string) - The configured webhook endpoint URL.
  - **event_types** (array of strings) - The list of event types subscribed to.
  - **created_at** (string) - The timestamp when the subscription was created.
  - **updated_at** (string) - The timestamp when the subscription was last updated.

#### Response Example
```json
{
  "subscriptions": [
    {
      "subscription_id": "sub_123abc",
      "endpoint": "https://example.com/webhook",
      "event_types": [
        "order.created"
      ],
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:30:00Z"
    },
    {
      "subscription_id": "sub_456def",
      "endpoint": "https://another.com/hook",
      "event_types": [
        "product.updated"
      ],
      "created_at": "2023-10-26T15:00:00Z",
      "updated_at": "2023-10-26T15:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Create Blog Item Template (HTML/JSON-T)

Source: https://developers.squarespace.com/beginner-tutorial

Specifies the markup for an individual blog post item using JSON‑T. It renders the post title with appropriate link handling ands body content. this as blog.item to control how each post appears within the collection.

```HTML
{.section item}

  <!--WRAPPER-->

  <article id="post-{id}" class="{@|item-classes}" data-item-id="{id}">

    <!--POST TILE-->

    <h1 class="title" data-content-field="title">
      {.passthrough?}        <a href="{sourceUrl}" target="_blank">{title}</a>
      {.or}
        <a href="{fullUrl}">{title}</a>
      {.end}
    </h1>

    <!--MAIN CONTENT-->

    {body}

  </article>

{.end}
```

--------------------------------

### Transactions API - Retrieve All Transactions

Source: https://developers.squarespace.com/commerce-apis/about-product-attributes

Gets a list of all transactions associated with the store.

```APIDOC
## GET /transactions

### Description
Retrieves all transactions in the store.

### Method
GET

### Endpoint
/transactions

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of transactions to return.
- **offset** (integer) - Optional - The number of transactions to skip.

### Response
#### Success Response (200)
- **transactions** (array of objects) - An array of transaction objects.
  - **transactionId** (string) - The unique identifier for the transaction.
  - **orderId** (string) - The ID of the associated order.
  - **amount** (object) - The transaction amount.
    - **currency** (string) - ISO 4217 currency code.
    - **value** (string) - The amount value as a string.
  - **status** (string) - The status of the transaction (e.g., 'SUCCESS', 'FAILED').
  - **createdAt** (string) - Timestamp when the transaction occurred.

#### Response Example
```json
{
  "transactions": [
    {
      "transactionId": "txn_abcdef123456",
      "orderId": "ord_abcdef123456",
      "amount": {"currency": "USD", "value": "50.00"},
      "status": "SUCCESS",
      "createdAt": "2023-10-27T10:05:00Z"
    }
  ]
}
```
```

--------------------------------

### Create Product via Squarespace API (curl)

Source: https://developers.squarespace.com/commerce-apis/create-product

This curl command demonstrates how to create a new product in Squarespace. It includes necessary headers like Authorization and Content-Type, and a detailed JSON payload specifying product type, variants, pricing, and more. The example covers required and optional fields with their constraints.

```shell
curl "https://api.squarespace.com/{api-version}/commerce/products/" \
  -i \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{' \
  '"type": "PHYSICAL",' \
  '"storePageId": "5d7ba084a63ee8bb410ce0b1",'\
  '"name": "Artisanal Steak Dry Rub",' \
  '"description": "<p>This can be a few words or even a few <i>paragraphs</i>.</p>",' \
  '"urlSlug": "artisanal-steak-dry-rub",' \
  '"tags": ["artisanal", "steak"],' \
  '"isVisible": true,' \
  '"variantAttributes": ["Flavor"],' \
  '"variants": [' \
    '{' \
      '"sku": "SQ0557856",' \
      '"pricing": {' \
        '"basePrice": {' \
          '"currency": "USD",' \
          '"value": "12.95"' \
        '},' \
        '"onSale": false,' \
        '"salePrice": {' \
          '"currency": "USD",' \
          '"value": "0.00"' \
        '}' \
      '}' \
    '}' \
  ']' \
'}'
```

--------------------------------

### Products API

Source: https://developers.squarespace.com/oauth

Comprehensive endpoints for managing products, including creating, updating, deleting products and their variants, images, and attributes.

```APIDOC
## Products API Endpoints

### POST /products

**Description**: Creates a new product in the store.

**Method**: POST

**Endpoint**: `/products`

### POST /products/{product_id}/variants

**Description**: Creates a new product variant for an existing product.

**Method**: POST

**Endpoint**: `/products/{product_id}/variants`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.

### POST /products/{product_id}/images

**Description**: Uploads a new image for a product.

**Method**: POST

**Endpoint**: `/products/{product_id}/images`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.

### GET /products

**Description**: Retrieves a list of all products.

**Method**: GET

**Endpoint**: `/products`

### GET /products/{product_id}

**Description**: Retrieves details of a specific product by its ID.

**Method**: GET

**Endpoint**: `/products/{product_id}`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.

### POST /products/{product_id}/variants/{variant_id}/images

**Description**: Assigns an image to a specific product variant.

**Method**: POST

**Endpoint**: `/products/{product_id}/variants/{variant_id}/images`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.
- **variant_id** (string) - Required - The unique identifier of the product variant.

### POST /products/{product_id}/images/{image_id}/reorder

**Description**: Reorders the images associated with a product.

**Method**: POST

**Endpoint**: `/products/{product_id}/images/{image_id}/reorder`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.
- **image_id** (string) - Required - The unique identifier of the image.

### PUT /products/{product_id}

**Description**: Updates an existing product.

**Method**: PUT

**Endpoint**: `/products/{product_id}`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.

### PUT /products/{product_id}/variants/{variant_id}

**Description**: Updates an existing product variant.

**Method**: PUT

**Endpoint**: `/products/{product_id}/variants/{variant_id}`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.
- **variant_id** (string) - Required - The unique identifier of the product variant.

### PUT /products/{product_id}/images/{image_id}

**Description**: Updates an existing product image.

**Method**: PUT

**Endpoint**: `/products/{product_id}/images/{image_id}`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.
- **image_id** (string) - Required - The unique identifier of the image.

### DELETE /products/{product_id}

**Description**: Deletes a product.

**Method**: DELETE

**Endpoint**: `/products/{product_id}`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product to delete.

### DELETE /products/{product_id}/variants/{variant_id}

**Description**: Deletes a product variant.

**Method**: DELETE

**Endpoint**: `/products/{product_id}/variants/{variant_id}`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.
- **variant_id** (string) - Required - The unique identifier of the product variant to delete.

### DELETE /products/{product_id}/images/{image_id}

**Description**: Deletes a product image.

**Method**: DELETE

**Endpoint**: `/products/{product_id}/images/{image_id}`

**Parameters**:
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.
- **image_id** (string) - Required - The unique identifier of the image to delete.
```

--------------------------------

### Delete Product Variant - cURL Request Example

Source: https://developers.squarespace.com/commerce-apis/delete-product-variant

An example of how to delete a product variant using cURL. This request includes necessary headers such as Authorization and User-Agent, and specifies the DELETE HTTP method. Remember to replace placeholders with your actual API key or OAuth token and application description.

```bash
curl "https://api.squarespace.com/{api-version}/commerce/products/123/variants/456" \
 -i \
 -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
 -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION" \
 -X DELETE
```

--------------------------------

### Example JSON for Pricing Information

Source: https://developers.squarespace.com/commerce-apis/update-product-variant

Demonstrates the JSON format for product variant pricing, including base price and sale price with currency and value. It also indicates if the item is currently on sale.

```json
{
  "basePrice": {
    "currency": "USD",
    "value": "22.95"
  },
  "salePrice": {
    "currency": "USD",
    "value": "17.99"
  },
  "onSale": true
}
```

--------------------------------

### GET /inventory/{variantId}

Source: https://developers.squarespace.com/commerce-apis/inventory-overview

Retrieve specific inventory information for a given product variant.

```APIDOC
## GET /inventory/{variantId}

### Description
Retrieve specific inventory information for a given product variant.

### Method
GET

### Endpoint
`/inventory/{variantId}`

### Parameters
#### Path Parameters
- **variantId** (string) - Required - The ID of the product variant.

### Response
#### Success Response (200)
- **variantId** (string) - The ID of the product variant.
- **sku** (string) - The stock keeping unit (SKU) code.
- **availability** (string) - The availability status ('in_stock', 'out_of_stock', 'unlimited').
- **quantity** (integer) - The current stock quantity.

#### Response Example
```json
{
  "variantId": "variant_123",
  "sku": "TSHIRT-RED-L",
  "availability": "in_stock",
  "quantity": 50
}
```
```

--------------------------------

### Squarespace API Document Response Example (JSON)

Source: https://developers.squarespace.com/commerce-apis/retrieve-specific-transactions

A successful Squarespace API request returns a JSON object containing an array of Document resources. Each document represents either an order or a donation and includes detailed financial information, customer data, and payment transaction specifics. This example demonstrates the typical structure and fields returned.

```json
{
  "documents": [
    {
      "id": "a7e4c6b5-d1fe-4e42-a932-f185b4b86829",
      "createdOn": "2019-11-18T21:20:05.354Z",
      "modifiedOn": "2019-11-18T21:23:02.870Z",
      "customerEmail": "customer@squarespace.com",
      "salesOrderId": "5d71991aac180c3e7857e1df",
      "voided": false,
      "totalSales": {
        "currency": "USD",
        "value": "150.00"
      },
      "totalNetSales": {
        "currency": "USD",
        "value": "145.00"
      },
      "totalNetShipping": {
        "currency": "USD",
        "value": "5.95"
      },
      "totalTaxes": {
        "currency": "USD",
        "value": "15.00"
      },
      "total": {
        "currency": "USD",
        "value": "165.00"
      },
      "totalNetPayment": {
        "currency": "USD",
        "value": "104.50"
      },
      "payments": [
        {
          "id": "ece69479-50bc-4763-9067-4473f3abcf83",
          "amount": {
            "currency": "USD",
            "value": "120.00"
          },
          "refundedAmount": {
            "currency": "USD",
            "value": "60.00"
          },
          "netAmount": {
            "currency": "USD",
            "value": "60.00"
          },
          "creditCardType": "VISA",
          "provider": "STRIPE",
          "refunds": [
            {
              "id": "cfdb6b87-64bf-461a-b48b-eca7bd2389fc",
              "amount": {
                "currency": "USD",
                "value": "60.00"
              },
              "refundedOn": "2019-11-18T21:22:06.500Z",
              "externalTransactionId": "re_1Flhp8J4wh083J8f7qYtzU9m"
            }
          ],
          "processingFees": [
            {
              "id": "2Jdsno3mdk",
              "amount": {
                "currency": "USD",
                "value": "1.00"
              },
              "amountGatewayCurrency": {
                "currency": "USD",
                "value": "1.00"
              },
              "exchangeRate": "1.0",
              "refundedAmount": {
                "currency": "USD",
                "value": "0.50"
              }
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Example JSON for Product Image Details

Source: https://developers.squarespace.com/commerce-apis/update-product-variant

Provides the JSON format for product image data associated with a variant, including ID, alt text, URL, original size, and available formats for different resolutions.

```json
{
  "id": "5ed539bc8367410cdc0c984a",
  "altText": "Steak",
  "url": "https://static1.squarespace.com/static/steak.png",
  "originalSize": {
    "width": 512,
    "height": 256
  },
  "availableFormats": ["100w", "300w", "500w"]
}
```

--------------------------------

### GET /webhooks/subscriptions/{subscription_id}

Source: https://developers.squarespace.com/commerce-apis/webhook-subscriptions-overview

Retrieves the details of a specific webhook subscription using its unique identifier.

```APIDOC
## GET /webhooks/subscriptions/{subscription_id}

### Description
Retrieves details for a specific webhook subscription.

### Method
GET

### Endpoint
`/webhooks/subscriptions/{subscription_id}`

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the webhook subscription to retrieve.

### Response
#### Success Response (200 OK)
- **subscription_id** (string) - The unique identifier for the webhook subscription.
- **endpoint** (string) - The configured webhook endpoint URL.
- **event_types** (array of strings) - The list of event types subscribed to.
- **created_at** (string) - The timestamp when the subscription was created.
- **updated_at** (string) - The timestamp when the subscription was last updated.

#### Response Example
```json
{
  "subscription_id": "sub_123abc",
  "endpoint": "https://example.com/webhook",
  "event_types": [
    "order.created"
  ],
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:30:00Z"
}
```
```

--------------------------------

### Products API - Overview

Source: https://developers.squarespace.com/commerce-apis/products-overview

The Products API allows merchants to manage product information on their Squarespace sites. This includes creating, retrieving, updating, and deleting products, their variants, and associated images. It also provides access to store page information.

```APIDOC
## Products API

### Description
Use the Products API to manage product information on a Squarespace merchant site, including variants of a product and product images. This API allows products to be retrieved, added, deleted, or modified with information such as a name or URL slug, a variant's color, size, or weight, or a new product image.

### Versions
- **v2 (Beta)**: Latest version with enhanced product type support (physical, service, gift card, download). Note: Download products cannot be created or deleted via v2 API.
- **v1.1, v1.0 (Legacy)**: Stable versions. Recommended to use v2 for new integrations.

### Product Visibility
Product visibility for purchase is determined by:
1. **Store Page Status**: Enabled or disabled in Squarespace UI > Pages > Store Page > gear icon > Store Settings editor > General. Disabled pages make products inaccessible.
2. **Product Details Page Status**: 'Visible' or 'Hidden' in the product editor. 'Hidden' makes the product details page unavailable to customers.

### Resources
- **StorePage**: Represents information for a Store Page. Each Product belongs to a single StorePage.
- **Product**: Represents a product on a merchant site.

### API Endpoints (Examples)

#### GET /products

##### Description
Retrieve all products.

##### Method
GET

##### Endpoint
`/v2/products`

#### GET /products/{productId}

##### Description
Retrieve a specific product.

##### Method
GET

##### Endpoint
`/v2/products/{productId}`

#### POST /products

##### Description
Create a new product.

##### Method
POST

##### Endpoint
`/v2/products`

#### PUT /products/{productId}

##### Description
Update an existing product.

##### Method
PUT

##### Endpoint
`/v2/products/{productId}`

#### DELETE /products/{productId}

##### Description
Delete a product.

##### Method
DELETE

##### Endpoint
`/v2/products/{productId}`

#### GET /store-pages

##### Description
Retrieve all Store Pages.

##### Method
GET

##### Endpoint
`/v2/store-pages`

#### GET /store-pages/{storePageId}/products

##### Description
Retrieve all products belonging to a specific Store Page.

##### Method
GET

##### Endpoint
`/v2/store-pages/{storePageId}/products

### Request Body Example (POST /products)
```json
{
  "name": "New T-Shirt",
  "urlSlug": "new-t-shirt",
  "storePageId": "your_store_page_id",
  "attributes": [
    {
      "name": "Color",
      "value": "Blue"
    }
  ]
}
```

### Response Example (GET /products/{productId})
```json
{
  "id": "prod_12345",
  "name": "Cool T-Shirt",
  "urlSlug": "cool-t-shirt",
  "storePageId": "store_abcde",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z",
  "attributes": [
    {
      "name": "Color",
      "value": "Red"
    },
    {
      "name": "Size",
      "value": "M"
    }
  ]
}
```
```

--------------------------------

### Clone Squarespace Site Repository

Source: https://developers.squarespace.com/local-development

Git command to clone a Squarespace site repository for local development. Requires the site to be in Developer Mode.

```shell
git clone https://github.com/{{ your_org }}/{{ your_repo }}.git
cd {{ your_repo }}
```

--------------------------------

### GET /commerce/transactions

Source: https://developers.squarespace.com/commerce-apis/retrieve-all-transactions

Retrieves all financial transactions for orders and donations. Supports time-boxing and pagination through cursor-based navigation.

```APIDOC
## GET /commerce/transactions

### Description
Retrieves all financial transactions for orders and donations. Per order and donation, the response groups transactions into a `Document`, contains up to 50 `Documents` ordered by their modification date (`modifiedOn`), and supports dynamic cursors for pagination.

### Method
GET

### Endpoint
`https://api.squarespace.com/{api-version}/commerce/transactions`

### Parameters
#### Path Parameters
- **api-version** (string) - Required - See the Transactions API Overview page for the current API version.

#### Query Parameters
- **modifiedAfter** (string) - Optional - Time-boxes the request to `Documents` that were modified after the specified ISO 8601 UTC date and time string.
- **modifiedBefore** (string) - Optional - Time-boxes the request to `Documents` that were modified before the specified ISO 8601 UTC date and time string.
- **cursor** (string) - Optional - Identifies where the next page of results should begin. Should be the value of `pagination.nextPageCursor` from a previous response.

### Request Example
```
curl "https://api.squarespace.com/1.0/commerce/transactions?modifiedAfter=2018-01-01T12:00:00Z&modifiedBefore=2019-01-15T14:30:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
```

### Response
#### Success Response (200)
- **documents** (array) - List of transaction documents.
- **pagination** (object) - Pagination information including nextPageCursor if more results are available.

#### Response Example
```json
{
  "documents": [
    {
      "id": "transaction123",
      "modifiedOn": "2019-01-10T10:30:00Z",
      "amount": {
        "value": "100.00",
        "currency": "USD"
      }
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "nextPageCursor": "abc123"
  }
}
```
```

--------------------------------

### Squarespace Dynamic Featured Query Example

Source: https://developers.squarespace.com/custom-query-tag

This example shows how to dynamically query for featured blog posts using the Squarespace Custom Query Tag. It's designed for a .list file and pulls the collection URL ID dynamically. The snippet displays featured posts with images and titles, making it reusable across different collection pages.

```Squarespace Template Language
blog.list
----------------------------

<squarespace:query collection="{.section collection}{urlId}{.end}" featured="true" limit="5">

  <div class="featured-wrapper">
    {.repeated section items}
    <div class="featured-post">
      {.main-image?}<img {@|image-meta} />{.end}
      <h2>{title}</h2>
    </div>
    {.end}
  </div>

</squarespace:query>
```