Template Docs Commerce APIs Tools
Get Started
Get Started

Retrieving All Orders

GET https://api.squarespace.com/1.0/commerce/orders?modifiedAfter={a}&modifiedBefore={b}&cursor={c}&fulfillmentStatus={d}

Retrieves order information with optional time-boxing and support for pagination. By checking this endpoint periodically, you can receive both recently created orders and updates to existing orders. A page can contain up to 50 orders and it is guaranteed that subsequent requests to the same URL will return the same objects and ordering.

Parameters

  • cursor optional
    • Type: A string token, returned from the pagination.nextPageCursor of a previous response.
    • Identifies where the next page of results should begin. If this parameter is not present or empty, the first page of order data will be returned.
  • modifiedAfter optional, required when modifiedBefore is present
    • Type: An ISO 8601 date and time string, e.g. 2016-04-10T12:00:00Z.
    • Time-boxes request to orders that were modified after this time.
  • modifiedBefore optional, required when modifiedAfter is present
    • Type: An ISO 8601 date and time string.
    • Time-boxes request to orders that were modified before this time.
  • fulfillmentStatus optional
    • Type: An enumerated string value of PENDING, FULFILLED, or CANCELED.
    • Used to filter orders according to their fulfillment status.

Note that requests must not specify both a cursor and a modification time range; either a cursor OR a modification time range may be specified. Filtering by fulfillment status may be used at anytime.

Request Example

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

Response Format

A response to a successful request will provide a JSON-formatted body containing a list of order resources and some pagination details.

{
  "result": [
    {
      "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",
        "variantId": "88c16ee4-547b-445e-a392-bded9991ae30",
        "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,
        "imageUrl" : "https://static.squarespace.com/universal/commerce/images/brine-32oz-spring-mix-v2.jpg?format=300w"
      } ],
      "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": [
        {
          "shipDate": "2017-01-28T22:19:26.980Z",
          "carrierName": "USPS",
          "service": "Priority Mail",
          "trackingNumber": "9400109699939624119857",
          "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=9400109699939624119857"
        }, {
          "shipDate": "2017-01-29T22:19:26.980Z",
          "carrierName": "FedEx",
          "service": "Same-Day Delivery",
          "trackingNumber": "103932814692659",
          "trackingUrl": "https://www.fedex.com/apps/fedextrack/?tracknumbers=103932814692659"
        }
      ],
      "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"
      }
    }
  ],
  "pagination": {
    "hasNextPage": true
    "nextPageCursor": "b342f5367c664d3c99aa56f44f95ab0a",
    "nextPageUrl": "https://api.squarespace.com/1.0/commerce/inventory?cursor=b342f5367c664d3c99aa56f44f95ab0a"
  }
}
  • result: An array of order resource objects, which will be empty if the store doesn't have any orders yet.
  • pagination: An object containing the following fields:
    • hasNextPage: a flag indicating whether another page of order data is available.
    • nextPageCursor nullable: the cursor that would be used in a subsequent request to retrieve the next page of data.
    • nextPageUrl nullable: a pre-built URL that applications can use to automatically request the next page of data.

Status Codes & Error Conditions

  • 200 OK
    • The request was successful. The message body contains data in the format specified above.
  • 400 BAD REQUEST
    • Type: INVALID_REQUEST_ERROR
    • Subtype: INVALID_ARGUMENT
      1. The value contained in the cursor parameter is invalid.
      2. modifiedAfter is not a valid ISO 8601 date and time.
      3. modifiedBefore is not a valid ISO 8601 date and time.
      4. modifiedBefore occurred before or at the same time as modifiedAfter.
      5. fulfillmentStatus is not a recognized value.
    • Subtype: MISSING_ARGUMENT
      1. One of modifiedAfter or modifiedBefore were specified without the other parameter.