> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Squarespace as a data source

> Bring orders, transactions, products, inventory, discounts and customers from Squarespace to Nekt.

Squarespace is a platform to build and host websites and online stores. This connector reads the commerce data of one Squarespace site through the Squarespace Commerce APIs: **orders** and their **line items**, financial **transactions** (payments, fees and refunds), **products** and **variants**, **inventory**, **store pages**, **discounts**, and the site's **contacts** and **profiles** (customers, subscribers and donors, with their order and donation totals).

<Note>
  The connector only reads data. It never creates, changes or deletes anything in Squarespace.
</Note>

<Warning>
  Squarespace only lets sites on the **Advanced** plan (formerly **Commerce Advanced**) generate the Developer API key this connector uses. Sites on other plans cannot be connected.
</Warning>

## Configuring Squarespace as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Squarespace option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The connector uses a **Developer API key** of the site. To create it:

1. Log in to Squarespace as the site owner or an administrator and open the site.
2. Go to **Settings > Developer Tools > Developer API Keys** (in older menus: **Settings > Advanced > Developer API Keys**) and click **Generate key**.
3. Name the key (for example, `Nekt`) and tick, with **Read Only** access, the permissions of the data you want: **Orders**, **Transactions**, **Products**, **Inventory**, **Contacts**, **Profiles** and **Discounts**.
4. Copy the key. Squarespace shows it only once. The key does not expire while the site is active.

<Info>
  A key's permissions cannot be changed later. If you need a permission you did not tick, generate a new key and update the source.
</Info>

The following configurations are available:

* **API Key**: the key copied above.

* **Start Date** (advanced): only orders and transactions modified on or after this date are extracted. Leave it empty to extract the whole history. Products, inventory, discounts, contacts and profiles are always extracted in full.

<Tip>
  Each API key belongs to one site. To extract several sites (for example, the sites an agency manages), create one source per site. Every table has a `website_id` column, so the tables of different sites can be combined in a Query.
</Tip>

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

<Info>
  Each selected stream needs its permission on the API key (see the table below). If a stream that is read in full (FULL\_TABLE) lacks its permission, the run stops before writing anything and lists the missing permissions. An incremental stream without its permission is skipped with a warning, and its table is left unchanged.
</Info>

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: Orders, Order Line Items, Transactions and Products support INCREMENTAL, the recommended type: each run reads only what changed since the previous one. Product Variants, Inventory, Discounts, Contacts, Profiles, Store Pages and Website are FULL\_TABLE: they are read in full on every run, so your tables always show their current state (a variant removed from a product, for example, leaves the table on the next run). Read more about Sync Types [here](https://docs.nekt.com/get-started/core-concepts/types-of-sync).

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. It also removes from the incremental tables the products and orders deleted in Squarespace, and the lines removed from an existing order.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API), the API key permission it needs and a short description.

| Stream | Slug | Permission | Description |
| - | - | - | - |
| Orders | `orders` | Orders | One row per order, in every payment state (including payment plan orders still being paid), with totals, addresses and fulfillment. |
| Order Line Items | `order_line_items` | Orders | One row per purchased item: product, variant, SKU, quantity and unit price paid. |
| Transactions | `transactions` | Transactions | One row per order or donation with its payments, processing fees, refunds and taxes. |
| Discounts | `discounts` | Discounts | Discounts and promo codes, with trigger, criteria, amount and number of uses. |
| Products | `products` | Products | Physical, service, gift card and download products. |
| Product Variants | `product_variants` | Products | One row per product variant, with SKU, attributes, prices and shipping measurements. |
| Inventory | `inventory` | Inventory | Current stock of each physical and service variant. |
| Store Pages | `store_pages` | Products | Store pages of the site. |
| Contacts | `contacts` | Contacts | Customers, subscribers and donors, with marketing opt-in and default shipping address. |
| Profiles | `profiles` | Profiles | Customers, subscribers and donors, with their order and donation totals. |
| Website | `website` | None | The site of the API key: title, URL, currency, language and time zone. |

Amounts are split into a `_value` column (decimal) and a `_currency` column (ISO code), for example `grand_total_value` and `grand_total_currency`. Lists such as line items, payments, images and notes are kept as JSON text in their own column; addresses are split into one column per field.

## Fields by stream

### Sales

<AccordionGroup>
  <Accordion title="Orders">
    One row per order (one-time and subscription orders), in every payment state, with totals, addresses and fulfillment status.

    Table: `orders` · Primary key: `id` · Sync: Incremental (`modified_on`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the order. |
    | `order_number` | String | Sequential number of the order shown to the merchant. |
    | `created_on` | Datetime | When the order was placed (UTC). |
    | `modified_on` | Datetime | When the order was last modified (UTC), used as the incremental replication key. |
    | `channel` | String | Where the order originated: web or pos. |
    | `channel_name` | String | Name of the third-party sales channel, for imported orders. |
    | `external_order_reference` | String | Order reference used by the third-party sales channel, for imported orders. |
    | `customer_id` | String | Id of the customer (same as the contact and profile id). |
    | `customer_email` | String | Email address entered at checkout. |
    | `testmode` | Boolean | Whether the order was placed with a payment method in test mode. |
    | `fulfillment_status` | String | Fulfillment status: PENDING, FULFILLED or CANCELED. |
    | `fulfilled_on` | Datetime | When the order was fulfilled (UTC). |
    | `payment_state` | String | Payment state: NOT\_CHARGED, AUTHORIZED, PAID, PARTIALLY\_PAID (payment plan), PENDING, FAILED, REFUND\_PENDING, REFUNDED or REFUND\_FAILED. |
    | `price_tax_interpretation` | String | Whether line item prices include tax: EXCLUSIVE or INCLUSIVE. |
    | `shipping_option_name` | String | Shipping service selected at checkout. |
    | `shipping_option_service_type` | String | Carrier service type identifier. |
    | `subtotal_value` | Number | Subtotal of the order (decimal amount). |
    | `subtotal_currency` | String | ISO 4217 currency of the subtotal of the order. |
    | `shipping_total_value` | Number | Shipping total of the order (decimal amount). |
    | `shipping_total_currency` | String | ISO 4217 currency of the shipping total of the order. |
    | `discount_total_value` | Number | Discount total of the order (decimal amount). |
    | `discount_total_currency` | String | ISO 4217 currency of the discount total of the order. |
    | `tax_total_value` | Number | Tax total of the order (decimal amount). |
    | `tax_total_currency` | String | ISO 4217 currency of the tax total of the order. |
    | `refunded_total_value` | Number | Refunded total of the order (decimal amount). |
    | `refunded_total_currency` | String | ISO 4217 currency of the refunded total of the order. |
    | `grand_total_value` | Number | Grand total of the order (decimal amount). |
    | `grand_total_currency` | String | ISO 4217 currency of the grand total of the order. |
    | `billing_first_name` | String | First name on the billing address. |
    | `billing_last_name` | String | Last name on the billing address. |
    | `billing_address1` | String | Street address of the billing address. |
    | `billing_address2` | String | Second address line of the billing address. |
    | `billing_city` | String | City of the billing address. |
    | `billing_state` | String | State or province of the billing address. |
    | `billing_postal_code` | String | Postal or ZIP code of the billing address. |
    | `billing_country_code` | String | ISO 3166-1 alpha-2 country of the billing address. |
    | `billing_phone` | String | Phone number on the billing address. |
    | `shipping_first_name` | String | First name on the shipping address. |
    | `shipping_last_name` | String | Last name on the shipping address. |
    | `shipping_address1` | String | Street address of the shipping address. |
    | `shipping_address2` | String | Second address line of the shipping address. |
    | `shipping_city` | String | City of the shipping address. |
    | `shipping_state` | String | State or province of the shipping address. |
    | `shipping_postal_code` | String | Postal or ZIP code of the shipping address. |
    | `shipping_country_code` | String | ISO 3166-1 alpha-2 country of the shipping address. |
    | `shipping_phone` | String | Phone number on the shipping address. |
    | `line_item_count` | Integer | Number of line items in the order. |
    | `line_items` | String | Purchased items as returned by the API (JSON array); see the order\_line\_items stream. |
    | `discount_lines` | String | Promotions redeemed at checkout (JSON array of objects). |
    | `shipping_lines` | String | Shipping options chosen at checkout (JSON array). |
    | `fulfillments` | String | Shipments of the order with carrier and tracking (JSON array). |
    | `internal_notes` | String | Internal notes added by the merchant (JSON array). |
    | `form_submission` | String | Checkout form answers (JSON array of label/value). |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>

  <Accordion title="Order Line Items">
    One row per purchased item of an order: product, variant, SKU, quantity and unit price paid.

    Table: `order_line_items` · Primary key: `order_id`, `id` · Sync: Incremental (`order_modified_on`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the line item (its position when the API sends none). |
    | `order_id` | String | Id of the order the item belongs to. |
    | `order_number` | String | Sequential number of the order. |
    | `order_created_on` | Datetime | When the order was placed (UTC). |
    | `line_index` | Integer | Position of the item in the order (0-based). |
    | `line_item_type` | String | Product type of the item (e.g. PHYSICAL\_PRODUCT, SERVICE, GIFT\_CARD, DIGITAL). |
    | `product_id` | String | Id of the purchased product. |
    | `variant_id` | String | Id of the purchased product variant. |
    | `product_name` | String | Name of the purchased product. |
    | `sku` | String | SKU of the purchased variant (null for digital products). |
    | `quantity` | Integer | Units purchased. |
    | `unit_price_paid_value` | Number | Unit price paid for the item (decimal amount). |
    | `unit_price_paid_currency` | String | ISO 4217 currency of the unit price paid for the item. |
    | `variant_options` | String | Variant choices made by the customer (JSON array). |
    | `customizations` | String | Answers to the product's custom form (JSON array). |
    | `image_url` | String | URL of the item's primary image. |
    | `weight` | Number | Shipping weight of the item (0 when not specified). |
    | `width` | Number | Shipping width of the item (0 when not specified). |
    | `length` | Number | Shipping length of the item (0 when not specified). |
    | `height` | Number | Shipping height of the item (0 when not specified). |
    | `order_modified_on` | Datetime | When the order was last modified (UTC), used as the incremental replication key. |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>

  <Accordion title="Transactions">
    One row per financial document (one per order or donation): payments, processing fees, refunds, taxes and net totals.

    Table: `transactions` · Primary key: `id` · Sync: Incremental (`modified_on`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the transaction document (one per order or donation). |
    | `sales_order_id` | String | Id of the order; null when the document is a donation. |
    | `created_on` | Datetime | When the document was created (UTC). |
    | `modified_on` | Datetime | When the document was last modified (UTC), used as the incremental replication key. |
    | `customer_email` | String | Customer or donor email (may be null for point of sale). |
    | `voided` | Boolean | Whether the order was canceled. |
    | `payment_gateway_error` | String | Error reported by the payment gateway, if any (fee processing, API permission, disconnected). |
    | `total_value` | Number | Grand total of the document (decimal amount). |
    | `total_currency` | String | ISO 4217 currency of the grand total of the document. |
    | `total_sales_value` | Number | Total item sales (decimal amount). |
    | `total_sales_currency` | String | ISO 4217 currency of the total item sales. |
    | `total_net_sales_value` | Number | Total item sales net of discounts (decimal amount). |
    | `total_net_sales_currency` | String | ISO 4217 currency of the total item sales net of discounts. |
    | `total_net_shipping_value` | Number | Total shipping net of discounts (decimal amount). |
    | `total_net_shipping_currency` | String | ISO 4217 currency of the total shipping net of discounts. |
    | `total_taxes_value` | Number | Total taxes (decimal amount). |
    | `total_taxes_currency` | String | ISO 4217 currency of the total taxes. |
    | `total_net_payment_value` | Number | Total paid net of processing fees and refunds (decimal amount). |
    | `total_net_payment_currency` | String | ISO 4217 currency of the total paid net of processing fees and refunds. |
    | `payment_count` | Integer | Number of payments collected (installments included). |
    | `payments` | String | Payments with gateway, card type, amounts, processing fees and refunds (JSON array of objects). |
    | `discounts` | String | Discounts applied to the order (JSON array of objects). |
    | `sales_line_items` | String | Sold items with totals and taxes (JSON array). |
    | `shipping_line_items` | String | Shipping charges with taxes (JSON array). |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>

  <Accordion title="Discounts">
    Discounts and promo codes of the site, with their trigger, criteria, amount and usage.

    Table: `discounts` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the discount. |
    | `name` | String | Display name of the discount. |
    | `status` | String | Lifecycle status: ACTIVE, SCHEDULED or EXPIRED. |
    | `valid_from` | Datetime | When the discount becomes active (UTC). |
    | `valid_to` | Datetime | When the discount expires (UTC); null means no expiry. |
    | `trigger_type` | String | How the discount is applied: AUTO or CODE (promo code). |
    | `promo_code` | String | Promo code the shopper enters (CODE trigger only). |
    | `criteria_type` | String | What the cart must contain: ANY\_ORDER, CART\_TOTAL, PRODUCT or BUY\_X\_GET\_Y. |
    | `template_type` | String | Kind of reduction: FIXED\_AMOUNT, PERCENTAGE, FREE\_SHIPPING, BUY\_X\_GET\_Y\_FIXED\_AMOUNT or BUY\_X\_GET\_Y\_PERCENTAGE. |
    | `discount_percentage` | Number | Percentage taken off (PERCENTAGE and BUY\_X\_GET\_Y\_PERCENTAGE templates). |
    | `discount_amount_value` | Number | Fixed amount taken off (decimal amount). |
    | `discount_amount_currency` | String | ISO 4217 currency of the fixed amount taken off. |
    | `minimum_cart_total_value` | Number | Minimum cart total required (CART\_TOTAL criteria) (decimal amount). |
    | `minimum_cart_total_currency` | String | ISO 4217 currency of the minimum cart total required (cart\_total criteria). |
    | `criteria` | String | Full eligibility criteria (JSON object). |
    | `template` | String | Full discount template (JSON object). |
    | `is_limited_uses` | Boolean | Whether the discount can only be used a limited number of times. |
    | `max_uses_allowed` | Integer | Maximum site-wide redemptions when uses are limited. |
    | `is_once_per_customer` | Boolean | Whether each customer can use the discount only once. |
    | `number_of_uses` | Integer | Times the discount has been redeemed. |
    | `last_redeemed_at` | Datetime | When the discount was last redeemed (UTC). |
    | `subscription_options_type` | String | How the discount applies to subscriptions: EXCLUDED, ALL\_PAYMENTS or LIMITED\_PAYMENTS. |
    | `payment_plan_options_type` | String | How the discount applies to payment plans: NONE or ALL\_PAYMENTS. |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>
</AccordionGroup>

### Catalog

<AccordionGroup>
  <Accordion title="Products">
    Products of every type (physical, service, gift card and download), with visibility, store page, SEO and images.

    Table: `products` · Primary key: `id` · Sync: Incremental (`modified_on`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the product. |
    | `type` | String | Product type: PHYSICAL, SERVICE, GIFT\_CARD or DIGITAL (download). |
    | `name` | String | Name of the product. |
    | `description` | String | Description of the product (HTML). |
    | `url` | String | Absolute URL of the product page. |
    | `url_slug` | String | URL slug of the product page. |
    | `store_page_id` | String | Id of the store page the product belongs to. |
    | `is_visible` | Boolean | Whether the product is visible for purchase (a hidden product cannot be bought). |
    | `tags` | Array of strings | Tags of the product. |
    | `seo_title` | String | Title used for search engine optimization. |
    | `seo_description` | String | Description used for search engine optimization. |
    | `variant_attributes` | Array of strings | Names of the attributes that distinguish the variants (e.g. Size, Color). |
    | `variant_count` | Integer | Number of variants of the product. |
    | `variants` | String | Variants of the product as returned by the API (JSON array); see the product\_variants stream. |
    | `images` | String | Images of the product (JSON array of objects). |
    | `digital_good_id` | String | Id of the downloadable file (download products only). |
    | `digital_good_filename` | String | Filename of the downloadable file (download products only). |
    | `base_price_value` | Number | Base price of a download product (decimal amount). |
    | `base_price_currency` | String | ISO 4217 currency of the base price of a download product. |
    | `on_sale` | Boolean | Whether a download product is sold at its sale price. |
    | `sale_price_value` | Number | Sale price of a download product (decimal amount). |
    | `sale_price_currency` | String | ISO 4217 currency of the sale price of a download product. |
    | `created_on` | Datetime | When the product was created (UTC). |
    | `modified_on` | Datetime | When the product was last modified (UTC), used as the incremental replication key. |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>

  <Accordion title="Product Variants">
    One row per product variant: SKU, attributes, prices, sale price and shipping measurements.

    Table: `product_variants` · Primary key: `product_id`, `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the variant. |
    | `product_id` | String | Id of the product the variant belongs to. |
    | `product_type` | String | Type of the product: PHYSICAL, SERVICE or GIFT\_CARD. |
    | `product_name` | String | Name of the product the variant belongs to. |
    | `variant_index` | Integer | Position of the variant in the product (0-based). |
    | `sku` | String | Stock keeping unit (SKU) code of the variant. |
    | `gtin` | String | Global Trade Item Number of the variant (physical products). |
    | `mpn` | String | Manufacturer Part Number of the variant (physical products). |
    | `attributes` | String | Attribute values of the variant, e.g. \{"Size": "Large"} (JSON object). |
    | `base_price_value` | Number | Base price of the variant (decimal amount). |
    | `base_price_currency` | String | ISO 4217 currency of the base price of the variant. |
    | `on_sale` | Boolean | Whether the variant is sold at its sale price. |
    | `sale_price_value` | Number | Sale price of the variant (decimal amount). |
    | `sale_price_currency` | String | ISO 4217 currency of the sale price of the variant. |
    | `weight_value` | Number | Shipping weight of the variant (physical products). |
    | `weight_unit` | String | Unit of the shipping weight: KILOGRAM or POUND. |
    | `length` | Number | Shipping length of the variant (physical products). |
    | `width` | Number | Shipping width of the variant (physical products). |
    | `height` | Number | Shipping height of the variant (physical products). |
    | `dimensions_unit` | String | Unit of the shipping dimensions: INCH or CENTIMETER. |
    | `image_id` | String | Id of the product image assigned to the variant. |
    | `image_url` | String | URL of the product image assigned to the variant. |
    | `product_modified_on` | Datetime | When the product the variant belongs to was last modified (UTC). |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>

  <Accordion title="Inventory">
    Current stock of every physical and service product variant.

    Table: `inventory` · Primary key: `variant_id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `variant_id` | String | Id of the product variant (also the inventory item id). |
    | `sku` | String | Stock keeping unit (SKU) code of the variant. |
    | `descriptor` | String | Description generated from the product title and the variant attributes (e.g. color, size). |
    | `is_unlimited` | Boolean | Whether the variant has unlimited stock (stock is not tracked). |
    | `quantity` | Integer | Units in stock, or the last known amount before the stock became unlimited. |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>

  <Accordion title="Store Pages">
    Store pages of the site; every product belongs to one store page.

    Table: `store_pages` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the store page. |
    | `title` | String | Title of the store page. |
    | `url_slug` | String | URL slug of the store page. |
    | `is_enabled` | Boolean | Whether the store page is enabled; products of a disabled page cannot be purchased. |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>
</AccordionGroup>

### People

<AccordionGroup>
  <Accordion title="Contacts">
    Customers, mailing list subscribers and donors, with marketing opt-in and default shipping address.

    Table: `contacts` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the contact (same as the order customer\_id and profile id). |
    | `first_name` | String | First name of the contact. |
    | `last_name` | String | Last name of the contact. |
    | `locale` | String | Locale of the contact. |
    | `created_on` | Datetime | When the contact was created (UTC). |
    | `email` | String | Primary email address of the contact. |
    | `email_created_on` | Datetime | When the primary email was added (UTC). |
    | `accepts_marketing` | Boolean | Whether the contact accepts marketing email. |
    | `marketing_joined_on` | Datetime | When the contact joined the marketing list (UTC). |
    | `marketing_left_on` | Datetime | When the contact left the marketing list (UTC). |
    | `default_shipping_address_id` | String | Id of the address book entry used as default shipping address. |
    | `default_shipping_first_name` | String | First name on the default shipping address. |
    | `default_shipping_last_name` | String | Last name on the default shipping address. |
    | `default_shipping_line1` | String | First line of the default shipping address. |
    | `default_shipping_line2` | String | Second line of the default shipping address. |
    | `default_shipping_city` | String | City of the default shipping address. |
    | `default_shipping_region` | String | Region (state, province, county) of the default shipping address. |
    | `default_shipping_postal_code` | String | Postal code of the default shipping address. |
    | `default_shipping_country_code` | String | ISO 3166 alpha-2 country of the default shipping address. |
    | `default_shipping_phone_number` | String | Phone number on the default shipping address. |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>

  <Accordion title="Profiles">
    Customers, subscribers and donors with their order and donation totals.

    Table: `profiles` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the profile (same as the contact id). |
    | `first_name` | String | First name of the profile. |
    | `last_name` | String | Last name of the profile. |
    | `email` | String | Email address of the profile. |
    | `has_account` | Boolean | Whether the profile has an account on the website. |
    | `is_customer` | Boolean | Whether the profile has any order or donation. |
    | `accepts_marketing` | Boolean | Whether the profile opted in to marketing. |
    | `created_on` | Datetime | When the profile was created (UTC). |
    | `address_first_name` | String | First name on the approximate address Squarespace derives from the profile's orders. |
    | `address_last_name` | String | Last name on the approximate address Squarespace derives from the profile's orders. |
    | `address_address1` | String | Street address of the approximate address Squarespace derives from the profile's orders. |
    | `address_address2` | String | Second address line of the approximate address Squarespace derives from the profile's orders. |
    | `address_city` | String | City of the approximate address Squarespace derives from the profile's orders. |
    | `address_state` | String | State or province of the approximate address Squarespace derives from the profile's orders. |
    | `address_postal_code` | String | Postal or ZIP code of the approximate address Squarespace derives from the profile's orders. |
    | `address_country_code` | String | ISO 3166-1 alpha-2 country of the approximate address Squarespace derives from the profile's orders. |
    | `address_phone` | String | Phone number on the approximate address Squarespace derives from the profile's orders. |
    | `order_count` | Integer | Number of orders placed. |
    | `total_order_amount_value` | Number | Total amount of all orders (decimal amount). |
    | `total_order_amount_currency` | String | ISO 4217 currency of the total amount of all orders. |
    | `total_refund_amount_value` | Number | Total amount refunded (decimal amount). |
    | `total_refund_amount_currency` | String | ISO 4217 currency of the total amount refunded. |
    | `first_order_submitted_on` | Datetime | When the first order was placed (UTC). |
    | `last_order_submitted_on` | Datetime | When the latest order was placed (UTC). |
    | `donation_count` | Integer | Number of donations submitted. |
    | `total_donation_amount_value` | Number | Total amount of all donations (decimal amount). |
    | `total_donation_amount_currency` | String | ISO 4217 currency of the total amount of all donations. |
    | `first_donation_submitted_on` | Datetime | When the first donation was submitted (UTC). |
    | `last_donation_submitted_on` | Datetime | When the latest donation was submitted (UTC). |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>
</AccordionGroup>

### Site

<AccordionGroup>
  <Accordion title="Website">
    The Squarespace site of the API key: title, URL, currency, language and time zone.

    Table: `website` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique id of the website that owns the API key. |
    | `site_id` | String | Identifier (subdomain) of the website within squarespace.com. |
    | `title` | String | Title of the website. |
    | `url` | String | Canonical URL of the website (its custom domain when available). |
    | `currency` | String | ISO 4217 currency the website uses for commerce. |
    | `measurement_standard` | String | Measurement standard used for product dimensions: IMPERIAL or METRIC. |
    | `language` | String | ISO language and country code of the website (e.g. en-US). |
    | `time_zone` | String | Time zone configured for the website (e.g. America/New\_York). |
    | `location_region` | String | Region of the business location (city, state and postal code; no street address). |
    | `location_country` | String | Country of the business location. |
    | `website_id` | String | Id of the Squarespace website the API key belongs to; lets tables of several sites be combined. |
  </Accordion>
</AccordionGroup>

## Implementation Notes

### What is not available

The Squarespace Commerce APIs do not expose site traffic analytics (visits, page views, traffic sources), form submissions, blog posts or page content, or email campaigns, so this connector cannot extract them. Appointments booked through Squarespace Scheduling come from Acuity Scheduling; use the [Acuity connector](https://docs.nekt.com/sources/acuity) for them.

### Data Quality Considerations

* **Donations** are not orders: they only appear in Transactions, with an empty `sales_order_id`.
* **Refunds** made directly in the payment provider (for example, in Stripe or PayPal) are not reported by Squarespace; only refunds made in Squarespace appear in Transactions.
* **Stock**: use the Inventory table for current stock. The `variants` column of Products reflects each product's last change, not later sales.
* **Deleted records**: products and orders deleted in Squarespace, and lines removed from an existing order (rare), stay in the incremental tables until the next full sync. Tables read in full, including Product Variants, drop them on the next run.
* **Contacts and Profiles** describe the same people with the same `id`, which is also the `customer_id` of Orders. Profiles carry the order and donation totals; Contacts carry the marketing opt-in dates and the default shipping address.
* Each run reads the changes made up to the moment it started. A change saved while a run is in progress is read by the next run (tables read in full pick it up at the end of the same run). Each incremental run also starts one hour before the point where the previous run stopped, as a margin for changes Squarespace records late. A row read twice is kept once in the table.

### API Limits & Performance

* Squarespace allows 300 requests per minute per site. The connector stays below that; if Squarespace still asks it to slow down (for example, because other integrations use the same site), the run waits about a minute and continues.
* Orders, transactions and products are read 50 per request; contacts up to 1,000 per request. Orders are read in two passes (by payment state) and products in four (one per product type), so a run makes a few more requests than its number of pages. A pass that comes back empty (for example, a store with no gift cards) is double-checked with a few extra requests, shared by the streams of the run. Order Line Items and Product Variants read the order and product lists themselves, so selecting them adds one request per 50 orders or products.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "Squarespace rejected the API key" | The key is wrong, was revoked, or was not copied whole. | Generate a new key in **Settings > Developer Tools > Developer API Keys** and update the source. |
| The option to generate a Developer API key is missing | The site is not on the Advanced plan (formerly Commerce Advanced). | Upgrade the site's plan; other plans cannot generate API keys. |
| The run stops listing missing permissions | The key does not have the permission of a stream that is read in full. | Generate a key with those permissions (Read Only is enough), or deselect the streams. |
| Warning: a stream was skipped because the key cannot read it | An incremental stream lacks its permission; its table was not updated. | Generate a key with the permission, or deselect the stream. |
| "This website's subscription has expired" | Squarespace blocks the API of sites with an expired plan. | Renew the site's plan and run the source again. |
| "Squarespace returned an inconsistent list" or "kept failing" | Squarespace's API answered with an error or a list that contradicts itself. Streams read in full load nothing from that run; incremental streams continue from their last saved point on the next run. | Run the source again. If it persists, contact support with the source slug and the run ID. |
| "Squarespace did not apply the filters" | Squarespace returned orders or products outside the payment states, product types or dates the connector asked for, so rows could be missing. The run stops instead of loading an incomplete list. | Contact support with the source slug and the run ID. |

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

<Card title="Download Squarespace skills file" icon="wand-magic-sparkles" href="/sources/squarespace.md">
  Squarespace connector documentation as plain markdown, for use in AI agent contexts.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.