Create an order

POST https://api.squarespace.com/{api-version}/commerce/orders

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

Some Squarespace merchants sell their products on third-party sales channels. By using this endpoint, a third-party order can be imported into Squarespace without affecting accounting data. The endpoint also has the option to send an order fulfillment notification to the customer via Squarespace.

Read the Overview to learn more about Orders.

Note: Before using this endpoint, confirm that the products for the third-party order are available on the Squarespace merchant site. If not, create them in Squarespace. Requests to create an order without an existing Squarespace products results in an error.

Rate Limiting

An additional layer of rate limiting is applied to this endpoint. Requests are limited to 100 per hour, per website. If you are frequently receiving a 429 responses, please consider spacing out your requests more. See Rate Limiting for additional info.

Parameters

{api-version} string
required

See the Orders API Overview page for the current API version.

Request example

Read the Making requests guide to learn why specific headers are necessary, and why some are omitted. Every request should also abide by Squarespace rate limits.

curl "https://api.squarespace.com/1.0/commerce/orders/" \
  -i \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{' \
  # Required; string, 30 char limit. Name of third-party sales channel.
  '"channelName": "Non-Squarespace Store",' \
  # Required; string, 200 char limit.
  # Order reference identifier used by the third-party sales channel.
  '"externalOrderReference": "ORDER1234567",' \
  # Optional; string. Email address provided at checkout on the third-party sales channel.
  '"customerEmail": "john@example.com",' \
  # Optional; object. Customer's billing address.
  # Unless specified, all fields are optional and have a string value with a 100 char limit.
  '"billingAddress": {' \
    '"firstName": "John",' \
    '"lastName": "Doe",' \
    # Required; string, 100 char limit.
    '"address1": "8 Clarkson Street",' \
    '"address2": "Unit 2F",' \
    '"city": "New York",' \
    '"state": "NY",' \
    # Required; ISO 3166 alpha-2 country code string.
    '"countryCode": "US",' \
    # Optional; string, 30 char limit.
    '"postalCode": "10014",' \
    # Optional; string, 30 char limit.
    '"phone": "999-999-9999"' \
  '},' \
  # Optional; object. Customer's shipping address.
  # Unless specified, all fields are optional and have a string value with a 100 char limit.
  '"shippingAddress": {' \
    '"firstName": "Jane",' \
    '"lastName": "Smith",' \
    # Required; string, 100 char limit.
    '"address1": "225 Varick Street",' \
    '"address2": "12th Floor",' \
    '"city": "New York",' \
    '"state": "NY",' \
    # Required; ISO 3166 alpha-2 country code string.
    '"countryCode": "US",' \
    # Optional; string, 30 char limit.
    '"postalCode": "10014",' \
    # Optional; string, 30 char limit.
    '"phone": "999-999-9999"' \
  '},' \
  # Optional; string. Indicates whether to deduct stock quantity
  # for the product variant upon Order creation.
  # Values may be `DEDUCT` or `SKIP`. If not specified, generated Order uses `SKIP`.
  '"inventoryBehavior": "SKIP",' \
  # Required; array of purchased line items; cannot be empty.
  # Line items describe what product variant was purchased,
  # how many of that item were purchased, and additional details.
  '"lineItems": [' \
    '{' \
      # Required; string. Product type sold; values may be `PHYSICAL_PRODUCT` or `CUSTOM`.
      # Use `CUSTOM` to describe additional costs for the order, such as gift wrapping or a service fee.
      '"lineItemType": "PHYSICAL_PRODUCT",' \
      # Conditional; string; field is required if lineItemType is `PHYSICAL_PRODUCT`.
      # Unique id of the ProductVariant sold.
      # See the Products API for information about ProductVariants.
      '"variantId": "AF705384-7641-4E8E-9F0A-C7E43BF88AB",' \
      # Required; number, 1,000,000 limit. Amount of the item purchased.
      # If inventoryBehavior is `SKIP`, then value can be any positive integer.
      # If inventoryBehavior is `DEDUCT`, then value has to be less than the available stock for the variant.
      # Use the Inventory API to retrieve stock information.
      '"quantity": 99,' \
      # Required; object. Price the customer paid per unit.
      '"unitPricePaid": {' \
        # Required; ISO 4217 currency code string.
        '"currency": "USD",' \
        # Required; string. 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.)
        '"value": "12.99"' \
      '},' \
      # Optional; object. The full unit price for the product variant when it's not on sale or discounted.
      # Value must be greater than or equal to unitPricePaid.
      '"nonSaleUnitPrice": {' \
        '"currency": "USD",' \
        '"value": "15.99"' \
      '}' \
    '},' \
    '{' \
      '"lineItemType": "CUSTOM",' \
      '"title": "Gift Wrapping",' \
      '"quantity": 1,' \
      '"unitPricePaid": {' \
        '"currency": "USD",' \
        '"value": "4.00"' \
      '},' \
      '"nonSaleUnitPrice": {' \
        '"currency": "USD",' \
        '"value": "4.00"' \
      '}' \
    '}' \
  '],' \
  # Optional; array of shipping line items. Describes the shipping options chosen at checkout.
  # Currently, the Orders API only accepts one shipping entry.
  # If the third-party order contains multiple shipments, combine them into one method and amount.
  '"shippingLines": [' \
    '{' \
      # Required; string 100 char limit. Description of the shipping option.
      '"method": "Flat Rate",' \
      # Required; object. Shipping cost.
      '"amount": {' \
        '"currency": "USD",' \
        '"value": "5.99"' \
      '}' \
    '}' \
  '],' \
  # Optional; array of discount line items.
  # Describes the promotions redeemed during checkout.
  '"discountLines": [' \
    '{' \
      # Required; string, 30 char limit. The promo code used.
      '"promoCode": "SPRING-20",' \
      # Required; string, 100 char limit. Name of the promotion.
      '"name": "Spring Discount 20% Off",' \
      # Required; object. Amount of the promotional discount.
      '"amount": {' \
        '"currency": "USD",' \
        '"value": "257.20"' \
      '}' \
    '}' \
  '],' \
  # Required; string. Indicates that lineItems.unitPricePaid includes tax.
  # Values may be `EXCLUSIVE` or `INCLUSIVE`.
  '"priceTaxInterpretation": "EXCLUSIVE",' \
  # Optional; object. Sum total of each lineItem's unitPricePaid multiplied by their respective quantity.
  # Sum total can't be more than 20,000,000; if not specified, value defaults to zero.
  '"subtotal": {' \
    '"currency": "USD",' \
    '"value": "1290.01"' \
  '},' \
  # Optional; object. Sum total of each shippingLine's amount.
  # Sum total can't be more than 20,000,000; if not specified, value defaults to zero.
  '"shippingTotal": {' \
    '"currency": "USD",' \
    '"value": "5.99"' \
  '},' \
  # Optional; object. Sum total of each discountLine's amount.
  # Sum total can't be more than 20,000,000;
  # if not specified, value defaults to zero.
  '"discountTotal": {' \
    '"currency": "USD",' \
    '"value": "257.20"' \
  '},' \
  # Optional; object. Sum total of the order's taxes,
  # when priceTaxInterpretation is `EXCLUSIVE`.
  # Sum total can't be more than 20,000,000; if not specified, value defaults to zero.
  '"taxTotal": {' \
    '"currency": "USD",' \
    '"value": "77.40"' \
  '},' \
  # Required; object. Complete total for the order,
  # representing the sum of subtotal, shippingTotal, and taxTotal, minus discountTotal.
  # Value can't be more than 20,000,000.
  '"grandTotal": {' \
    '"currency": "USD",' \
    '"value": "1116.20"' \
  '},' \
  # Optional; string. Current fulfillment status of the order.
  # Value may be `PENDING` or `FULFILLED`.  
  '"fulfillmentStatus": "FULFILLED",' \
  # Optional; string. Indicates whether to send a fulfillment notification email to the customer.
  # Value may be `SEND` or `SKIP`. If not specified, the generated Order uses `SKIP`.
  # To use `SEND`, read the specifications under "Multi-field validations".
  '"shopperFulfillmentNotificationBehavior": "SEND",' \
  # Conditional; ISO 8601 UTC date and time string.
  # Represents the moment the order was fulfilled.
  # If fulfillmentStatus is `FULFILLED`, field is required.
  '"fulfilledOn": "2017-01-29T22:19:26.980Z",' \
  # Required; array of shipping fulfillments; up to 100 entries.
  # Describes shipment information for the order.
  '"fulfillments": [' \
    '{' \
      # Required; ISO 8601 UTC date and time string.
      # Represents the moment the fulfillment was shipped by the third-party sales channel.
      '"shipDate": "2017-01-29T22:19:26.980Z",' \
      # Required; string  100 char limit. Name of the carrier handling the shipment.
      '"carrierName": "FedEx",' \
      # Required; string, 100 char limit. Carrier's level of service for shipping.
      '"service": "Same-Day Delivery",' \
      # Required; string, 100 char limit. Carrier's parcel tracking number.
      '"trackingNumber": "ABC 123",' \
      # Optional; string. URL provided by the carrier to track the shipment;
      # must adhere to valid URL formatting.
      '"trackingUrl": "https://fedex.com/track?q=ABC%20123"' \
    '}' \
  '],' \
  # Required; ISO 8601 UTC date and time string. Represents the date and time
  # when the order was placed through the third-party sales channel.
  '"createdOn": "2017-01-25T17:13:26.205Z"' \
'}' \

Precautions

Don't forget the Idempotency-Key header; it's required.

Read the Idempotency-Key header guide to learn more.

Multi-field validations

For customer notifications from Squarespace

To trigger a customer notification for a fulfilled third-party order, the following fields and values must be specified in the request:

'{'
  # Valid customer email
  '"customerEmail": "john@example.com",' \      
  '"fulfillmentStatus": "FULFILLED",' \
  '"shopperFulfillmentNotificationBehavior": "SEND"' \
'}'

Response example

A successful request generates a JSON response with the created Order.

Note: For easier reference between response fields and descriptions, comments were added in the example, though this makes the JSON invalid.

{
  // 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.
  "testmode" : 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`.
  "fulfillmentStatus" : "FULFILLED",
  // 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" : "Size"
    }, {
      "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" : [ {
    // Field is deprecated, use `name` instead.
    "description" : "Spring Discount 20% Off",
    // Name of the promotion.
    "name": "Fall Sale",
    // Amount of the promotional discount.
    "amount" : {
      "value" : "257.20",
      "currency" : "USD"
    },
    // The promo code used.
    "promoCode" : "SPRING-20"
  } ],
  // Array of shipping fulfillments;
  // describes shipment information for the order.
  "fulfillments": [
    {
      // ISO 8601 UTC date and time string; represents the moment the fulfillment was shipped.
      "shipDate": "2017-01-28T22:19:26.980Z",
      // Name of the carrier handling the shipment.
      "carrierName": "FedEx",
      // Carrier's level of service for shipping.
      "service": "Same-Day Delivery",
      // Carrier's parcel tracking number.
      "trackingNumber": "ABC 123",
      // URL provided by the carrier to track the shipment.
      "trackingUrl": "https://fedex.com/track?q=ABC%20123"
    }
  ],
  // Totals representing the amount of money spent on their
  // named concerns, such as shipping, taxes, et al.
  "subtotal" : {
    "value" : "1290.01",
    "currency" : "USD"
  },
  "shippingTotal" : {
    "value" : "5.99",
    "currency" : "USD"
  },
  "discountTotal" : {
    "value" : "257.20",
    "currency" : "USD"
  },
  "taxTotal" : {
    "value" : "77.40",
    "currency" : "USD"
  },
  "refundedTotal" : {
    "value" : "0.00",
    "currency" : "USD"
  },
  "grandTotal" : {
    "value" : "1116.20",
    "currency" : "USD"
  },
  // Name of the third-party sales channel.
  "channelName": "Non-Squarespace Store",
  // Order reference identifier used by the third-party sales channel.
  "externalOrderReference": "ORDER1234567",
  // ISO 8601 UTC date and time string; represents the moment the order was fulfilled.
  "fulfilledOn": "2017-01-30T22:18:37.480Z",
  // Indicates whether lineItems.unitPricePaid includes tax.
  // Values may be `EXCLUSIVE` or `INCLUSIVE`.
  "priceTaxInterpretation": "INCLUSIVE"
}

Status codes and error conditions

201 Created

The request was successful. The message body contains data in the format specified above. If this is a request with a previously used Idempotency-Key, the previous operation was successful and no new changes were made.

400 BAD REQUEST

Type: INVALID_REQUEST_ERROR

Subtype: null

• The request body does not conform to the required specification.
• The Idempotency-Key header is missing or invalid. Refer to the idempotency-key header guide for requirements.
• The provided Idempotency-Key has already been used by another request bearing a different body.

Subtype: PRODUCT_VARIANT_NOT_FOUND

• One or more specified product variants were not found.

409 CONFLICT

Type: CONFLICT

Subtype: CONCURRENT_MODIFICATION

• A request using the provided Idempotency-Key is already in progress.

Subtype: INSUFFICIENT_STOCK
One or more specified product variants have insufficient stock.

429 TOO MANY REQUESTS

Type: TOO_MANY_REQUESTS

Subtype: null

• The rate limit for this endpoint has been exceeded.