The Squarespace Orders API provides access to order history for a Squarespace merchant site, supporting both one-time purchases and subscription orders. Developers can retrieve, create, and manage orders, as well as import orders from third-party sales channels into Squarespace.
openapi: 3.1.0
info:
title: Squarespace Orders API
description: >-
The Squarespace Orders API provides access to order history for a Squarespace
merchant site, supporting both one-time purchases and subscription orders.
Developers can retrieve, create, and manage orders, as well as import orders
from third-party sales channels into Squarespace. The API supports filtering
by modification date and pagination via cursor for retrieving large sets of
orders. It is commonly used to synchronize order data with external fulfillment
systems, ERPs, or custom reporting tools.
version: '1.0'
contact:
name: Squarespace Developer Support
url: https://developers.squarespace.com/commerce-apis/orders-overview
termsOfService: https://www.squarespace.com/terms-of-service
externalDocs:
description: Squarespace Orders API Documentation
url: https://developers.squarespace.com/commerce-apis/orders-overview
servers:
- url: https://api.squarespace.com/1.0
description: Production Server
tags:
- name: Orders
description: Order management for one-time purchases and subscription orders
security:
- bearerAuth: []
paths:
/commerce/orders:
get:
operationId: listOrders
summary: Retrieve All Orders
description: >-
Returns a paginated list of orders for the authenticated merchant site.
By default returns up to 50 orders per page. Results can be filtered by
modification date using modifiedAfter and modifiedBefore parameters.
Use the cursor parameter from the previous response's pagination.nextPageCursor
to retrieve subsequent pages.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/cursor'
- name: modifiedAfter
in: query
description: >-
ISO 8601 UTC date-time string. Only returns orders modified after
this date and time.
required: false
schema:
type: string
format: date-time
- name: modifiedBefore
in: query
description: >-
ISO 8601 UTC date-time string. Only returns orders modified before
this date and time.
required: false
schema:
type: string
format: date-time
- name: fulfillmentStatus
in: query
description: Filter orders by fulfillment status
required: false
schema:
type: string
enum:
- PENDING
- FULFILLED
- CANCELED
responses:
'200':
description: Successful response with paginated list of orders
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Order'
pagination:
$ref: '#/components/schemas/Pagination'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createOrder
summary: Create an Order
description: >-
Creates a new order on the merchant site. This endpoint is primarily used
to import orders from third-party sales channels into Squarespace. The
order must include line items, customer information, and address details.
Creating an order does not process payment; it records the order as
already completed.
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'200':
description: Order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/orders/{orderId}:
get:
operationId: getOrder
summary: Retrieve a Specific Order
description: >-
Retrieves detailed information for a specific order by its unique identifier.
Returns the full Order resource object including line items, customer data,
addresses, fulfillments, and payment details.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/orderId'
responses:
'200':
description: Successful response with order details
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/orders/{orderId}/fulfillments:
post:
operationId: fulfillOrder
summary: Fulfill an Order
description: >-
Marks one or more line items in an order as fulfilled and optionally
records shipment tracking information. This updates the fulfillment
status of the specified line items and can trigger order fulfillment
notifications to the customer if configured.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/orderId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FulfillOrderRequest'
responses:
'200':
description: Order fulfillment recorded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate using an API key or OAuth access token. Include the token
in the Authorization header as "Bearer YOUR_TOKEN".
responses:
BadRequest:
description: The request was malformed or contained invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication credentials are missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The authenticated user does not have permission to access this resource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
cursor:
name: cursor
in: query
description: >-
Pagination cursor from a previous response's pagination.nextPageCursor field.
Omit or leave empty to retrieve the first page.
required: false
schema:
type: string
orderId:
name: orderId
in: path
description: The unique identifier of the order
required: true
schema:
type: string
schemas:
Order:
type: object
description: An order placed on a Squarespace merchant site
properties:
id:
type: string
description: Unique identifier for the order
orderNumber:
type: integer
description: Human-readable sequential order number displayed to customers
createdOn:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the order was created
modifiedOn:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the order was last modified
channel:
type: string
description: >-
The sales channel through which the order was placed, such as
SQUARESPACE or an external channel name
testmode:
type: boolean
description: Indicates whether the order was placed in test mode
customerEmail:
type: string
format: email
description: Email address of the customer who placed the order
billingAddress:
$ref: '#/components/schemas/Address'
shippingAddress:
$ref: '#/components/schemas/Address'
fulfillmentStatus:
type: string
description: Current fulfillment status of the order
enum:
- PENDING
- FULFILLED
- CANCELED
lineItems:
type: array
description: List of products and quantities included in the order
items:
$ref: '#/components/schemas/LineItem'
fulfillments:
type: array
description: List of fulfillment records associated with the order
items:
$ref: '#/components/schemas/Fulfillment'
totals:
$ref: '#/components/schemas/OrderTotals'
formSubmission:
type: array
description: Custom form fields submitted with the order
items:
$ref: '#/components/schemas/FormField'
refundedTotal:
$ref: '#/components/schemas/Money'
priceTaxInterpretation:
type: string
description: Indicates whether product prices are tax-inclusive or tax-exclusive
enum:
- EXCLUSIVE
- INCLUSIVE
CreateOrderRequest:
type: object
description: Request body for creating a new order
required:
- lineItems
- billingAddress
- shippingAddress
- customerEmail
- totals
properties:
externalOrderReference:
type: string
description: External reference identifier from the originating sales channel
customerEmail:
type: string
format: email
description: Email address of the customer who placed the order
billingAddress:
$ref: '#/components/schemas/Address'
shippingAddress:
$ref: '#/components/schemas/Address'
lineItems:
type: array
description: Products and quantities included in the order
items:
$ref: '#/components/schemas/LineItem'
totals:
$ref: '#/components/schemas/OrderTotals'
fulfillments:
type: array
description: Initial fulfillment records for the order
items:
$ref: '#/components/schemas/Fulfillment'
channel:
type: string
description: Name of the external sales channel the order was imported from
FulfillOrderRequest:
type: object
description: Request body for marking order line items as fulfilled
required:
- shouldSendNotification
- shipments
properties:
shouldSendNotification:
type: boolean
description: Whether to send a fulfillment notification email to the customer
shipments:
type: array
description: Shipment tracking details for the fulfilled items
items:
$ref: '#/components/schemas/Shipment'
Address:
type: object
description: A postal address for billing or shipping
properties:
firstName:
type: string
description: First name of the recipient
lastName:
type: string
description: Last name of the recipient
address1:
type: string
description: Primary street address line
address2:
type: string
description: Secondary address line such as apartment or suite number
city:
type: string
description: City name
state:
type: string
description: State, province, or region code
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code
pattern: '^[A-Z]{2}$'
postalCode:
type: string
description: Postal or ZIP code
phone:
type: string
description: Phone number associated with the address
LineItem:
type: object
description: A single product line in an order
properties:
id:
type: string
description: Unique identifier for the line item
variantId:
type: string
description: Unique identifier of the product variant
sku:
type: string
description: Stock keeping unit identifier for the product variant
productId:
type: string
description: Unique identifier of the parent product
productName:
type: string
description: Display name of the product at the time of purchase
quantity:
type: integer
minimum: 1
description: Number of units ordered
unitPricePaid:
$ref: '#/components/schemas/Money'
customizations:
type: array
description: Customer-provided customizations applied to the line item
items:
$ref: '#/components/schemas/Customization'
imageUrl:
type: string
format: uri
description: URL of the product image at the time of purchase
lineItemType:
type: string
description: The type of product represented by this line item
enum:
- PHYSICAL
- DIGITAL
- SERVICE
- GIFT_CARD
Fulfillment:
type: object
description: A fulfillment record indicating that part or all of an order has shipped
properties:
shipDate:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the shipment was sent
carrierName:
type: string
description: Name of the shipping carrier
service:
type: string
description: Name of the shipping service level used
trackingNumber:
type: string
description: Tracking number assigned by the carrier
trackingUrl:
type: string
format: uri
description: URL to track the shipment on the carrier website
Shipment:
type: object
description: Shipment details for a fulfillment record
properties:
shipDate:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the shipment was dispatched
carrierName:
type: string
description: Name of the shipping carrier
service:
type: string
description: Name of the shipping service used
trackingNumber:
type: string
description: Carrier-assigned tracking number for the shipment
trackingUrl:
type: string
format: uri
description: URL to the carrier's tracking page for this shipment
OrderTotals:
type: object
description: Monetary totals for an order
properties:
subtotal:
$ref: '#/components/schemas/Money'
shippingTotal:
$ref: '#/components/schemas/Money'
taxTotal:
$ref: '#/components/schemas/Money'
discountTotal:
$ref: '#/components/schemas/Money'
grandTotal:
$ref: '#/components/schemas/Money'
giftCardRedemptionTotal:
$ref: '#/components/schemas/Money'
Money:
type: object
description: A monetary value with currency
properties:
value:
type: string
description: Decimal string representation of the monetary amount
pattern: '^-?\d+(\.\d+)?$'
currency:
type: string
description: ISO 4217 three-letter currency code
pattern: '^[A-Z]{3}$'
FormField:
type: object
description: A custom form field submitted with an order
properties:
label:
type: string
description: Display label of the form field
value:
type: string
description: Value submitted by the customer for this field
Customization:
type: object
description: A customization option applied to a line item
properties:
label:
type: string
description: Display label of the customization option
value:
type: string
description: Customer-selected value for this customization
Pagination:
type: object
description: Pagination metadata included with list responses
properties:
hasNextPage:
type: boolean
description: Indicates whether additional pages of results are available
nextPageCursor:
type: string
description: Cursor value to pass in the next request to retrieve the next page
nextPageUrl:
type: string
format: uri
description: Full URL for retrieving the next page of results
Error:
type: object
description: Standard error response returned by the Squarespace API
properties:
type:
type: string
description: Machine-readable error type identifier
subtype:
type: string
description: Optional more specific error subtype
message:
type: string
description: Human-readable description of the error
statusCode:
type: integer
description: HTTP status code associated with the error