Squarespace Developer Platform: APIs, Apps, and Docs
Commerce API

Manage customer contacts and address book entries for a website: create, read, update, delete, and query contacts; maintain addresses for shipping and fulfillment.


List contacts

GET
https://api.squarespace.com
/v1/contacts

Returns a paginated list of contacts for the website. Requires OAuth website scope website.contacts.read or website.contacts, or API key scope CONTACT_READONLY or CONTACT, or OAuth website scope website.profiles.read or website.profiles (OAuth only).

List contacts › query Parameters

pageSize
​integer · int32 · min: 0 · max: 1000

number of contacts to retrieve per request

Default: 50
cursor
​string

where next page of results begins. should be {pagination.nextPageCursor} from previous response.

List contacts › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

List contacts › Responses

A paginated list of contacts.

​Contact[]

paginated list of contacts retrieved

​object

Create contact

POST
https://api.squarespace.com
/v1/contacts

Creates a new contact. Requires OAuth website scope website.contacts, or API key scope CONTACT, or OAuth website scope website.profiles (OAuth only).

Create contact › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Create contact › Request Body

firstName
​string · required

Contact's first name

Example: john
lastName
​string · required

Contact's last name

Example: doe
locale
​string · required

Contact's locale

Example: en-US
​CreateEmail · required

Primary email supplied when creating a contact.

Create contact › Responses

The created contact.

​Contact

A contact.


Query contacts

POST
https://api.squarespace.com
/v1/contacts/query

Returns a paginated list of contacts matching filters and sort options in the request body. Requires OAuth website scope website.contacts.read or website.contacts, or API key scope CONTACT_READONLY or CONTACT, or OAuth website scope website.profiles.read or website.profiles (OAuth only).

Query contacts › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Query contacts › Request Body

​AcceptsMarketingWithDate

Contact's marketing settings with joined on date

cursor
​string

The cursor for the next page of results. Use the value of pagination.nextPageCursor from the previous response.

​IntegerFilter

Object for filtering by a min and max integer

​IntegerFilter

Object for filtering by a min and max integer

​DateFilter

Object for filtering by before and after dates

​DateFilter

Object for filtering by before and after dates

​DateFilter

Object for filtering by before and after dates

​DateFilter

Object for filtering by before and after dates

​IntegerFilter

Object for filtering by a min and max integer

​IntegerFilter

Object for filtering by a min and max integer

pageSize
​integer · int32 · min: 1 · max: 1000

The number of contacts to return per request.

Default: 50
searchString
​string

Search string for Name and Email address

sortDirection
​string · enum

Direction to sort results, ASCENDING or DESCENDING

Enum values:
ASCENDING
DESCENDING
sortField
​string · enum

Field to sort results by

Enum values:
ID
CREATED_ON
EMAIL
ACCEPTS_MARKETING_JOINED_ON
FIRST_NAME
LAST_NAME
ORDER_COUNT
LAST_ORDER_ON

Query contacts › Responses

A paginated list of contacts matching the query.

​Contact[]

paginated list of contacts retrieved

​object

Get contact

GET
https://api.squarespace.com
/v1/contacts/{contactId}

Returns the contact for the given contact ID. Requires OAuth website scope website.contacts.read or website.contacts, or API key scope CONTACT_READONLY or CONTACT, or OAuth website scope website.profiles.read or website.profiles (OAuth only).

Get contact › path Parameters

contactId
​string · required

The contact's ID.

Get contact › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Get contact › Responses

The requested contact.

​Contact

A contact.


Delete contact

DELETE
https://api.squarespace.com
/v1/contacts/{contactId}

Deletes the contact for the given contact ID. Requires OAuth website scope website.contacts, or API key scope CONTACT, or OAuth website scope website.profiles (OAuth only).

Delete contact › path Parameters

contactId
​string · required

The contact's ID.

Delete contact › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Delete contact › Responses

No content.

No data returned

Update contact

PATCH
https://api.squarespace.com
/v1/contacts/{contactId}

Updates a contact using JSON merge patch. Requires OAuth website scope website.contacts, or API key scope CONTACT, or OAuth website scope website.profiles (OAuth only).

Update contact › path Parameters

contactId
​string · required

The contact's ID.

Update contact › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Update contact › Request Body

Fields to update on an existing contact.
firstName
​string

The contact's first name.

Example: John
lastName
​string

The contact's last name.

Example: Smith
locale
​string

The contact's locale.

Example: en-US
​PatchEmail

Primary email fields for an update request.

Example: {"email":"[email protected]","acceptsMarketing":true}

Update contact › Responses

The updated contact.

​Contact

A contact.


Get address book

GET
https://api.squarespace.com
/v1/contacts/{contactId}/address-book

Returns paginated addresses for the contact. When there is at least one entry, exactly one is the default shipping address (defaultShippingAddressId and each entry's defaultShipping reflect this). The default shipping address (when present) is always included on the first page of results. Requires OAuth website scope website.contacts.read or website.contacts, or API key scope CONTACT_READONLY or CONTACT, or OAuth website scope website.profiles.read or website.profiles (OAuth only).

Get address book › path Parameters

contactId
​string · required

The contact's ID.

Get address book › query Parameters

pageSize
​integer · int32 · min: 0 · max: 1000

number of contacts to retrieve per request

Default: 50
cursor
​string

where next page of results begins. should be {pagination.nextPageCursor} from previous response.

Get address book › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Get address book › Responses

Paginated list of the contact's addresses. When there is at least one entry, the first page always includes the default shipping address, and defaultShippingAddressId identifies it. On later pages, addressBookEntries is the next slice only; defaultShippingAddressId is present only when the default shipping entry appears in that slice.

​AddressBook

Address settings for a contact. When there is at least one address book entry, exactly one is the default shipping address; default shipping address is always returned on the first page of paginated results).

​PaginationDetails

Create address book entry

POST
https://api.squarespace.com
/v1/contacts/{contactId}/address-book

Creates a new address book entry for the contact. If this is the contact's only address book entry after creation, it becomes the default shipping address even when defaultShipping is false. Requires OAuth website scope website.contacts, or API key scope CONTACT, or OAuth website scope website.profiles (OAuth only).

Create address book entry › path Parameters

contactId
​string · required

The contact's ID.

Create address book entry › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Create address book entry › Request Body

​ContactAddress · required

Address properties for a contact.

defaultShipping
​boolean

Whether this entry should be the default shipping address. If this is the only address book entry for the contact after creation, it becomes the default even when set to false.

Create address book entry › Responses

The created address book entry.

​AddressBookEntry

An address book entry for a contact.


Get address book entry

GET
https://api.squarespace.com
/v1/contacts/{contactId}/address-book/{addressBookEntryId}

Returns a single address book entry for the contact. Requires OAuth website scope website.contacts.read or website.contacts, or API key scope CONTACT_READONLY or CONTACT, or OAuth website scope website.profiles.read or website.profiles (OAuth only).

Get address book entry › path Parameters

contactId
​string · required

The contact's ID.

addressBookEntryId
​string · required

The address book entry's ID.

Get address book entry › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Get address book entry › Responses

The requested address book entry.

​AddressBookEntry

An address book entry for a contact.


Replace address book entry

PUT
https://api.squarespace.com
/v1/contacts/{contactId}/address-book/{addressBookEntryId}

Replaces an address book entry for the contact with a full JSON body. When updating the entry that is currently the default, setting "defaultShipping" from true to false has no effect. Requires OAuth website scope website.contacts, or API key scope CONTACT, or OAuth website scope website.profiles (OAuth only).

Replace address book entry › path Parameters

contactId
​string · required

The contact's ID.

addressBookEntryId
​string · required

The address book entry's ID.

Replace address book entry › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Replace address book entry › Request Body

​ContactAddress · required

Address properties for a contact.

defaultShipping
​boolean

Whether this entry should be the default shipping address. When updating the entry that is currently the default, changing this value from true to false has no effect.

Replace address book entry › Responses

The updated address book entry.

​AddressBookEntry

An address book entry for a contact.


Delete address book entry

DELETE
https://api.squarespace.com
/v1/contacts/{contactId}/address-book/{addressBookEntryId}

Deletes the address book entry for the contact. If the deleted entry was the default shipping address, another entry is assigned as the default. Requires OAuth website scope website.contacts, or API key scope CONTACT, or OAuth website scope website.profiles (OAuth only).

Delete address book entry › path Parameters

contactId
​string · required

The contact's ID.

addressBookEntryId
​string · required

The address book entry's ID.

Delete address book entry › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Delete address book entry › Responses

No content.

No data returned