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

Orders

Download schema

List orders

GET
https://api.squarespace.com
/1.0/commerce/orders

Retrieves information about all orders. Orders can be filtered by Customer ID and date ranges. The response contains order information in an Order, up to 50 Orders ordered by their modification date (modifiedOn), and supports dynamic cursors for pagination.

List orders › query Parameters

customerId
​string

Used to filter Orders by Customer ID.

modifiedAfter
​string

Time-boxes the request to Orders that were modified after a given ISO 8601 UTC date and time string (YYYY-MM-DDThh:mm:ss.sZ). Required when modifiedBefore is passed; cannot be used with cursor.

modifiedBefore
​string

Time-boxes the request to Orders that were modified before a given ISO 8601 UTC date and time string (YYYY-MM-DDThh:mm:ss.sZ). Required when modifiedAfter is passed; cannot be used with cursor.

cursor
​string

Identifies where the next page of results should begin. Should be the value of pagination.nextPageCursor from a previous response. Cannot be used with other parameters.

fulfillmentStatus
​string

Used to filter Orders by fulfillment status. Values may be PENDING, FULFILLED, or CANCELED.

paymentStates
​string

Used to filter Orders by payment state. Accepts a comma-separated list of values. Possible values are: NOT_CHARGED, AUTHORIZED, PAID, REFUNDED, PENDING, FAILED, REFUND_PENDING, REFUND_FAILED, PARTIALLY_PAID. If not specified, defaults to NOT_CHARGED, AUTHORIZED, PAID, and REFUNDED.

List orders › 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 orders › Responses

A paginated list of orders.

OrderListResponse
​object
​Order[]

Create order

POST
https://api.squarespace.com
/1.0/commerce/orders

Creates an order using information from a third-party sales channel. A successful request creates an Order resource.

Create order › Headers

Idempotency-Key
​string · required

Idempotency key to prevent duplicate order creation.

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 order › Request Body

CreateOrderRequest
channelName
​string · maxLength: 30 · required

Name of third-party sales channel.

createdOn
​string · date-time · required

ISO 8601 UTC date and time string. Represents the date and time when the order was placed through the third-party sales channel.

externalOrderReference
​string · maxLength: 200 · required

Order reference identifier used by the third-party sales channel.

​CreateOrderShipmentRequest[] · required

Array of shipping fulfillments; up to 100 entries. Describes shipment information for the order.

​MonetaryAmount · required

A monetary amount with currency code and decimal value.

​CreateLineItemRequest[] · required

Array of purchased line items; cannot be empty.

priceTaxInterpretation
​TaxInterpretation · enum · required

Indicates that lineItems.unitPricePaid includes tax. Values may be EXCLUSIVE or INCLUSIVE.

Enum values:
INCLUSIVE
EXCLUSIVE
​AddressRequest

Customer's shipping address.

customerEmail
​string · email

Email address provided at checkout on the third-party sales channel.

Array of discount line items. Describes the promotions redeemed during checkout.

​MonetaryAmount

A monetary amount with currency code and decimal value.

fulfilledOn
​string · date-time

ISO 8601 UTC date and time string. Represents the moment the order was fulfilled. Required if fulfillmentStatus is FULFILLED.

fulfillmentStatus
​OrderCreateFulfillmentStatus · enum

Current fulfillment status of the order. Value may be PENDING or FULFILLED.

Enum values:
PENDING
FULFILLED
inventoryBehavior
​CreateOrderInventoryBehavior · enum

Indicates whether to deduct stock quantity for the product variant upon Order creation. Values may be DEDUCT or SKIP. Defaults to SKIP.

Enum values:
DEDUCT
SKIP
​AddressRequest

Customer's shipping address.

Array of shipping line items. Describes the shipping options chosen at checkout. Currently accepts only one shipping entry.

​MonetaryAmount

A monetary amount with currency code and decimal value.

shopperFulfillmentNotificationBehavior
​ShopperFulfillmentNotificationBehavior · enum

Indicates whether to send a fulfillment notification email to the customer. Value may be SEND or SKIP.

Enum values:
SEND
SKIP
​MonetaryAmount

A monetary amount with currency code and decimal value.

​MonetaryAmount

A monetary amount with currency code and decimal value.

Create order › Responses

The created order.

Order
​Address

Customer's shipping address provided at checkout or, for recurring subscription orders, the customer's current mailing address.

channel
​string

Where the order originated; possible values are: web and pos.

Example: web
channelName
​string

Name of the third-party sales channel.

Example: Faire Wholesale
createdOn
​string · date-time

ISO 8601 UTC date and time string; represents the moment when the order was placed.

Example: 2016-12-23T15:58:07.187Z
customerEmail
​string

Email address entered at checkout or, for recurring subscription orders, the customer's current email address.

customerId
​string

Unique customer id.

Example: 585d498fdee9f31a60284a38
​DiscountLine[]

Array of discount line items; describes the promotions redeemed during checkout.

​MonetaryAmount

A monetary amount with currency code and decimal value.

externalOrderReference
​string

Order reference identifier used by the third-party sales channel.

Example: EXT-98765
​FormItem[]

Array of form data submitted via the checkout page.

fulfilledOn
​string · date-time

ISO 8601 UTC date and time string; represents the moment the order was fulfilled.

fulfillmentStatus
​FulfillmentStatus · enum

Current fulfillment status of the order. Value may be: PENDING, FULFILLED, or CANCELED.

Enum values:
PENDING
FULFILLED
CANCELED
​Fulfillment[]

Array of shipping fulfillments; describes shipment information for the order.

​MonetaryAmount

A monetary amount with currency code and decimal value.

id
​string

Unique Order id.

Example: 585d498fdee9f31a60284a37
​OrderNote[]

Array of internal notes added to the order by the merchant.

​LineItem[]

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.

modifiedOn
​string · date-time

ISO 8601 UTC date and time string; represents when the order was last modified.

Example: 2016-12-23T15:58:07.187Z
orderNumber
​string

Unique, sequential number for the Order.

Example: 3
paymentState
​PaymentState · enum

Current state of payment for the order.

Enum values:
NOT_CHARGED
AUTHORIZED
PAID
REFUNDED
PENDING
FAILED
REFUND_PENDING
REFUND_FAILED
priceTaxInterpretation
​string

Indicates whether lineItems.unitPricePaid includes tax. Values may be EXCLUSIVE or INCLUSIVE.

Example: EXCLUSIVE
​MonetaryAmount

A monetary amount with currency code and decimal value.

​Address

Customer's shipping address provided at checkout or, for recurring subscription orders, the customer's current mailing address.

​ShippingLine[]

Array of shipping line items; describes the shipping options chosen at checkout.

shippingOptionName
​string

the specific shipping service name selected at checkout (e.g. "USPS Ground Advantage", "Royal Mail Tracked 48").

shippingOptionServiceType
​string · enum

The carrier service type identifier.

Enum values:
FEDEX_GROUND
FEDEX_GROUND_HOME_DELIVERY
FEDEX_PRIORITY_OVERNIGHT
FEDEX_STANDARD_OVERNIGHT
FEDEX_2_DAY
FEDEX_2_DAY_AM
FEDEX_EXPRESS_SAVER
FEDEX_FIRST_FREIGHT
​MonetaryAmount

A monetary amount with currency code and decimal value.

​MonetaryAmount

A monetary amount with currency code and decimal value.

​MonetaryAmount

A monetary amount with currency code and decimal value.

testmode
​boolean

If true, the order is a test order created using a payment method in test mode.

Get order

GET
https://api.squarespace.com
/1.0/commerce/orders/{id}

Retrieves information for a specific order. The response contains order information in an Order.

Get order › path Parameters

id
​string · required

Specifies the Order to retrieve.

Get order › 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 order › Responses

The requested order.

Order
​Address

Customer's shipping address provided at checkout or, for recurring subscription orders, the customer's current mailing address.

channel
​string

Where the order originated; possible values are: web and pos.

Example: web
channelName
​string

Name of the third-party sales channel.

Example: Faire Wholesale
createdOn
​string · date-time

ISO 8601 UTC date and time string; represents the moment when the order was placed.

Example: 2016-12-23T15:58:07.187Z
customerEmail
​string

Email address entered at checkout or, for recurring subscription orders, the customer's current email address.

customerId
​string

Unique customer id.

Example: 585d498fdee9f31a60284a38
​DiscountLine[]

Array of discount line items; describes the promotions redeemed during checkout.

​MonetaryAmount

A monetary amount with currency code and decimal value.

externalOrderReference
​string

Order reference identifier used by the third-party sales channel.

Example: EXT-98765
​FormItem[]

Array of form data submitted via the checkout page.

fulfilledOn
​string · date-time

ISO 8601 UTC date and time string; represents the moment the order was fulfilled.

fulfillmentStatus
​FulfillmentStatus · enum

Current fulfillment status of the order. Value may be: PENDING, FULFILLED, or CANCELED.

Enum values:
PENDING
FULFILLED
CANCELED
​Fulfillment[]

Array of shipping fulfillments; describes shipment information for the order.

​MonetaryAmount

A monetary amount with currency code and decimal value.

id
​string

Unique Order id.

Example: 585d498fdee9f31a60284a37
​OrderNote[]

Array of internal notes added to the order by the merchant.

​LineItem[]

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.

modifiedOn
​string · date-time

ISO 8601 UTC date and time string; represents when the order was last modified.

Example: 2016-12-23T15:58:07.187Z
orderNumber
​string

Unique, sequential number for the Order.

Example: 3
paymentState
​PaymentState · enum

Current state of payment for the order.

Enum values:
NOT_CHARGED
AUTHORIZED
PAID
REFUNDED
PENDING
FAILED
REFUND_PENDING
REFUND_FAILED
priceTaxInterpretation
​string

Indicates whether lineItems.unitPricePaid includes tax. Values may be EXCLUSIVE or INCLUSIVE.

Example: EXCLUSIVE
​MonetaryAmount

A monetary amount with currency code and decimal value.

​Address

Customer's shipping address provided at checkout or, for recurring subscription orders, the customer's current mailing address.

​ShippingLine[]

Array of shipping line items; describes the shipping options chosen at checkout.

shippingOptionName
​string

the specific shipping service name selected at checkout (e.g. "USPS Ground Advantage", "Royal Mail Tracked 48").

shippingOptionServiceType
​string · enum

The carrier service type identifier.

Enum values:
FEDEX_GROUND
FEDEX_GROUND_HOME_DELIVERY
FEDEX_PRIORITY_OVERNIGHT
FEDEX_STANDARD_OVERNIGHT
FEDEX_2_DAY
FEDEX_2_DAY_AM
FEDEX_EXPRESS_SAVER
FEDEX_FIRST_FREIGHT
​MonetaryAmount

A monetary amount with currency code and decimal value.

​MonetaryAmount

A monetary amount with currency code and decimal value.

​MonetaryAmount

A monetary amount with currency code and decimal value.

testmode
​boolean

If true, the order is a test order created using a payment method in test mode.

Fulfill order

POST
https://api.squarespace.com
/1.0/commerce/orders/{id}/fulfillments

Updates the status of a specific order to fulfilled, with options to include shipment information and send a customer notification.

Fulfill order › path Parameters

id
​string · required

Specifies the Order to update.

Fulfill order › 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

Fulfill order › Request Body

OrderFulfillmentRequest

Array of shipment data.

shouldSendNotification
​boolean

Indicates whether the customer should receive an email notification about the added shipments.

Fulfill order › Responses

No content. The order was successfully fulfilled.

No data returned
InventoryTransactions