Docs Tools
Get Started
Get Started

Commerce API

With the Squarespace Commerce API, you can build applications that manage data from your Squarespace store. HTTP endpoints are provided which allow you to:

  • Retrieve orders
  • (Coming soon) Update orders with fulfillment information

The API is built on HTTP and is designed with REST principles. All request and response body content is in JSON. We use HTTP features such as authentication, standard verbs, and standard status codes. All API endpoints are served from https://api.squarespace.com/<version>

Important Notes on Compatibility:

  • The current version is 0.1
  • Versions are specified in the URL path, e.g. https://api.squarespace.com/0.1/commerce/orders.

We may add bug fixes, new features, fields, and values to the API from time to time in a way that preserves backwards compatability. Develop your application to permit new keys to be added to objects without breaking. Breaking changes will only be introduced in a new, numbered version, and shouldn't affect your integration. For example: Version 1.2 would introduce some breaking changes to Version 1.1. In general, we'll support each API version for a long time, and we'll rarely introduce new breaking versions.

Authentication

You can authenticate by including a generated secret API Key in your request headers as a bearer token. Ensure that all requests are made over HTTPS. Unsecured requests will be rejected. For example:

curl "https://api.squarespace.com/0.1/commerce/orders/56f1806d7b863796cbc2ee81" -H "Authorization: Bearer YOUR_SECRET_API_KEY"

You can create a new key using the steps below. During the private beta, only beta participants will be able to access this functionality.

  1. In the Home Menu, click Settings, and then click Advanced.
  2. Click API Keys (Beta).
  3. Click Create Key.

Important Note: All requests must include the User-Agent HTTP header. Requests without one will be rejected.

Orders API

Retrieve a List of Orders

You can retrieve a list of recently modified orders by specifying a time window. By checking this endpoint periodically, you can receive both newly created orders and updates to existing orders. The /orders endpoint returns pages of 20 Orders at a time.

For results sets larger than 20 Orders, responses will include a nextPageCursor string under the pagination key that you can use to fetch the next page of results. To fetch the page, pass nextPageCursor in as the cursor argument while leaving modifiedAfter and modifiedBefore blank.

Endpoint

GET /commerce/orders

Arguments

  • modifiedAfter: (Date String) Orders retrieved were modified after this time.
  • modifiedBefore: (Date String) Orders retrieved were modified before this time.
  • cursor: (String) Opaque string used to page through result sets larger than 20 Orders
  • fulfillmentStatus: (String) Used to filter orders according to their fulfillmentStatus attribute. Valid values are: PENDING, FULFILLED, and CANCELED.

The date arguments must be formatted as an ISO 8601 date and time in UTC, e.g. “2007-04-05T14:30Z”

Example Request:

curl "https://api.squarespace.com/0.1/commerce/orders?modifiedAfter=2016-04-10T12:00:00Z&modifiedBefore=2016-04-15T12:30:00Z" -H "Authorization: Bearer YOUR_SECRET_API_KEY"

Response: A list response containing a list of Order objects.

Retrieve One Order

You can retrieve a single order by its id.

Endpoint

GET /commerce/orders/<id>

Arguments:

  • id: the Order’s id

Example Request:

curl "https://api.squarespace.com/0.1/commerce/orders/56f1806d7b863796cbc2ee81" -H "Authorization: Bearer YOUR_SECRET_API_KEY"

Response: An Order object.

Fulfill an Order

You can post a fulfillment of an order, which will change its fulfillment state to “FULFILLED” and optionally trigger an email notification to the shopper. It will update the order summary with the shipments sent during the fulfillment.

Endpoint

POST /commerce/orders/<id>/fulfillments

Arguments

  • In the body of the request, a FulfillmentRequest object
  • Id
    • The order’s Id

Example Request:

curl -X POST fulfillments" -d '{ "shouldSendNotification":true,
"shipments":[ { "shipDate":"2017-01-29T22:19:26.980Z",
"carrierName":"USPS", "service":"overnight", "trackingNumber":"defgh",
"trackingUrl":null }, { "shipDate":"2017-01-29T22:19:26.980Z",
"carrierName":"Usps", "service":"Priority Mail", "trackingNumber":"abcd",
"trackingUrl":"https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=abcd" } ] }' -H "Content-Type: application/json" -H "Authorization:
Bearer YOUR_SECRET_API_KEY"

Response: 204 No Content

Errors

HTTP Statuses

Squarespace uses the following standard HTTP response codes:

2xx

Codes in the 2xx range indicate a successful request.

  • 200 OK: Your request succeeded.
  • 201 Created: Your request to create a new resource succeeded. The response body will include the new object.
  • 204 No Content: Your request succeeded and there is no data in the response.

4xx

Codes in the 4xx range indicate that something is wrong with your application. You should receive an Error object in the response with more details to help you debug.

  • 400 Bad Request: We could not accept your request, probably because of malformed syntax, a missing argument, or an invalid argument.
  • 401 Unauthorized: We could not accept your request because you did not include your API Key or because your key is invalid or expired.
  • 404 Not Found: The resource could not be found.
  • 405 Method Not Allowed: You attempted to access a resource with an unsupported method.
  • 409 Conflict: Your request conflicted with another request, likely due to simultaneous requests competing for the same resource or an attempt to write an object with stale data.
  • 429 Too Many Requests: Your application issued too many requests in a short period of time.

5xx

Any errors in the 5xx range indicate a problem happened with Squarespace’s servers. You should receive an Error object in the response. Please report the issue and include the contextId you received.

Error Objects

All errors (both 4xx and 5xx range) will be returned with a standard Error object:

{
  type: "INVALID_REQUEST", // required. Type of error that happened.
  subtype: "MISSING_ARGUMENT", // optional. Subtype of the error.
  message: "Expiration date is required", // optional. A developer-centric message.
  details: { ... }, // optional. Contains more detailed data about the error.
  contextId: "RUPSUSPOW" // required. Used to trace the error in system logs.
}

Note: The message field is intended for you, the developer, and shouldn't be displayed to an end-user or client. The message field will typically contain detailed debug information.

Objects

Order

An order placed on Squarespace.

Attributes

  • ID The unique ID of this order
  • orderNumber The unique, sequential number for this order
  • createdOn When this order was created
  • testMode If true, this order was created with a test payment.
  • fulfillmentStatus The current status of the order in a fulfillment workflow. Values are: PENDING, FULFILLED, and CANCELED.
  • Email The customer’s email address entered at checkout
  • billingAddress The customer’s billing address
  • shippingAddress The customer’s shipping address
  • lineItems A list of LineItem objects that describe what items (and how many) were purchased, including customizations. Attributes:
    • id The line item’s unique ID
    • sku The SKU of the item
    • productId The unique ID of the product
    • productName The name / title of the product
    • Quantity How many of this item were purchased
    • unitPricePaid The price the shopper paid for one unit of this item
    • variantOptions A list of variant option choices made by the shopper, such as “Small, Red” for a t-shirt.
    • customizations A list of customizations the shopper entered
  • internalNotes A list of internal order notes. Attributes:
    • content The content of the note
  • formSubmission The shopper-entered results of a form at checkout
  • shippingLines A list of lines describing the shipping method(s) the shopper selected
  • subtotal, taxTotal, shippingTotal, discountTotal, grandTotal These fields represent the total amounts in this order.

Sample Response Object

{
  "id" : "585d498fdee9f31a60284a37",
  "orderNumber" : "3",
  "createdOn" : "2016-12-23T15:58:07.187Z",
  "modifiedOn" : "2016-12-23T15:58:07.187Z",
  "testmode" : true,
  "customerEmail" : "foo@example.com",
  "billingAddress" : {
    "firstName" : "Bob",
    "lastName" : "Loblaw",
    "address1" : "459 Broadway",
    "address2" : null,
    "city" : "New York",
    "state" : "NY",
    "countryCode" : "US",
    "postalCode" : "10003",
    "phone": "5553334444"
  },
  "shippingAddress" : {
    "firstName" : "Bob",
    "lastName" : "Loblaw",
    "address1" : "459 Broadway",
    "address2" : null,
    "city" : "New York",
    "state" : "NY",
    "countryCode" : "US",
    "postalCode" : "10003",
    "phone": "5553334444"
  },
  "fulfillmentStatus" : "PENDING",
  "lineItems" : [ {
    "id" : "585d4975dee9f31a60284a16",
    "sku" : "SQ3381024",
    "productId" : "565c8f3da7c8a3cf71d5fd0a",
    "productName" : "Product",
    "quantity" : 1,
    "unitPricePaid" : {
      "value" : "55.00",
      "currency" : "USD"
    },
    "variantOptions" : [ {
      "value" : "Large",
      "optionName" : "Size"
    }, {
      "value" : "Black",
      "optionName" : "Color"
    } ],
    "customizations" : null
  } ],
  "internalNotes" : [ {
      "content" : "First note"
    }, {
      "content" : "Second note"
  } ],
  "shippingLines" : [ {
    "method" : "Flat Rate",
    "amount" : {
      "value" : "1.00",
      "currency" : "USD"
    }
  } ],
  "discountLines" : [ {
    "description" : "Fall Sale",
    "amount" : {
      "value" : "1.00",
      "currency" : "USD"
    },
    "promoCode" : "FALLSALE"
  } ],
  "formSubmission" : [ {
    "label" : "How did you hear about us?",
    "value" : "Facebook"
  } ],
  "fulfillments" : [ ],
  "subtotal" : {
    "value" : "55.00",
    "currency" : "USD"
  },
  "shippingTotal" : {
    "value" : "1.00",
    "currency" : "USD"
  },
  "discountTotal" : {
    "value" : "1.00",
    "currency" : "USD"
  },
  "taxTotal" : {
    "value" : "2.70",
    "currency" : "USD"
  },
  "refundedTotal" : {
    "value" : "0.00",
    "currency" : "USD"
  },
  "grandTotal" : {
    "value" : "57.70",
    "currency" : "USD"
  }
}

FulfillmentStatus

Represents the current status of an order. Valid values are: PENDING, FULFILLED, or CANCELED

FulfillmentRequest

Represents a request to fulfill a given Order with the given shipments and associated data.

Attributes

  • shipments:
  • A list of Shipment objects.
  • shouldSendNotification:
  • A boolean. If this field is set to true, Squarespace will send an email to the customer who placed the order.

Sample Objects

{  
  "shouldSendNotification":true,
  "shipments":[  
     {  
        "shipDate":"2017-01-29T22:19:26.980Z",
        "carrierName":"USPS",
        "service":"overnight",
        "trackingNumber":"defgh",
        "trackingUrl":null
     },
     {  
        "shipDate":"2017-01-29T22:19:26.980Z",
        "carrierName":"Usps",
        "service":"Priority Mail",
        "trackingNumber":"abcd",
        "trackingUrl":"https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=abcd"
     }
   ]
}

Shipment

Attributes

  • shipDate
    • The date the shipment was sent
  • carrierName
    • A string representing the name of the carrier used to send the shipment (UPS, USPS, etc)
  • service:
    • The shipping service (Overnight, Next Day Express, etc).
  • trackingNumber
    • The shipment’s carrier-generated tracking number
  • trackingUrl (optional)
    • The tracking URL supplied by the carrier. If supplied, this field must be a valid URL.

Money

Represents a monetary value.

Attributes

  • Value A formatted string indicating the amount of money in the currency provided. This should be parsed into a decimal object.
  • Currency The ISO 4217 code representing the monetary value denomination.