Get Orders

This section includes comprehensive definitions of the request and response bodies for the Custom Store /orders endpoint.

Info If your cart or marketplace has data that you want to make available in ShipStation, but does not fit into one of these fields, contact us about making an integration using the full ShipStation ECommerceAPI.

Request URL Parameter Definitions

These are query string parameters that will be included in the HTTP Request from ShipStation.

Info The created_at_start and created_at_end parameters in the query string will be in the ISO 8601 format.

Name	Type	Required?	Description
`created_at_start`	date	No	Start date for order export. If omitted use the earliest order time.
`created_at_end`	date	No	End date for order export. If omitted use the current time.
`page`	number	No	The specific page of the paginated data what ShipStation would like to retrieve.

Example Request

ShipStation will make an HTTP GET request to the /orders endpoint to retrieve order related information from your connected Custom Store.

GET /orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z HTTP/1.1
Host: api.my-store.com
Authorization: Basic ZGVtbzpwQDU1dzByZA==
Accept: application/json

curl -iX GET 'https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z' \
-H 'Authorization: Basic ZGVtbzpwQDU1dzByZA==' \
-H 'Accept: application/json' \

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Host", "api.my-store.com")
$headers.Add("Authorization", "Basic ZGVtbzpwQDU1dzByZA==")
$headers.Add("Accept", "application/json")

$response = Invoke-RestMethod 'https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z' -Method 'GET' -Headers $headers -Body $body
$response | ConvertTo-Json

var myHeaders = new Headers();
myHeaders.append("Host", "api.my-store.com");
myHeaders.append("Authorization", "Basic ZGVtbzpwQDU1dzByZA==");
myHeaders.append("Accept", "application/json");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z',
  'headers': {
    'Host': 'api.my-store.com',
    'Authorization': 'Basic ZGVtbzpwQDU1dzByZA==',
    'Accept': 'application/json'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.my-store.com/orders?created_at_start=2020-01-17T05%253A42%253A50.000Z&created_at_end=2020-01-17T06%253A00%253A00.000Z",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Host: api.my-store.com",
    "Authorization: Basic ZGVtbzpwQDU1dzByZA==",
    "Accept: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z"

payload = {}
headers = {
  'Host': 'api.my-store.com',
  'Authorization': 'Basic ZGVtbzpwQDU1dzByZA==',
  'Accept': 'application/json'
}

response = requests.request("GET", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

require "uri"
require "net/http"

url = URI("https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Host"] = "api.my-store.com"
request["Authorization"] = "Basic ZGVtbzpwQDU1dzByZA=="
request["Accept"] = "application/json"

response = https.request(request)
puts response.read_body

var client = new RestClient("https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Host", "api.my-store.com");
request.AddHeader("Authorization", "Basic ZGVtbzpwQDU1dzByZA==");
request.AddHeader("Accept", "application/json");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z")
  .method("GET", null)
  .addHeader("Host", "api.my-store.com")
  .addHeader("Authorization", "Basic ZGVtbzpwQDU1dzByZA==")
  .addHeader("Accept", "application/json")
  .build();
Response response = client.newCall(request).execute();

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.my-store.com/orders?created_at_start=2020-01-17T05%253A42%253A50.000Z&created_at_end=2020-01-17T06%253A00%253A00.000Z"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Host", "api.my-store.com")
  req.Header.Add("Authorization", "Basic ZGVtbzpwQDU1dzByZA==")
  req.Header.Add("Accept", "application/json")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

#import <Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.my-store.com/orders?created_at_start=2020-01-17T05%253A42%253A50.000Z&created_at_end=2020-01-17T06%253A00%253A00.000Z"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.my-store.com",
  @"Authorization": @"Basic ZGVtbzpwQDU1dzByZA==",
  @"Accept": @"application/json"
};

[request setAllHTTPHeaderFields:headers];

[request setHTTPMethod:@"GET"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);

import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.my-store.com/orders?created_at_start=2020-01-17T05%3A42%3A50.000Z&created_at_end=2020-01-17T06%3A00%3A00.000Z")!,timeoutInterval: Double.infinity)
request.addValue("api.my-store.com", forHTTPHeaderField: "Host")
request.addValue("Basic ZGVtbzpwQDU1dzByZA==", forHTTPHeaderField: "Authorization")
request.addValue("application/json", forHTTPHeaderField: "Accept")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

Example Response

Your page should return data for any order that was modified between the created_at_start and created_at_end date range, regardless of the order's status. The order data should be returned in JSON format according to the schema provided in the Order definitions.

{
  "page": 1,
  "pages": 7,
  "orders": [
    {
      "order_id": "QsPJ9R-CfY4 BjnieMw68-Gb9TW9yp",
      "order_source_code": "shopify",
      "created_at": "2020-01-17T05:50:23.000Z",
      "modified_at": "2020-01-17T05:50:23.000Z",
      "status": "awaiting_shipment",
      "fulfillment_status": "partially_fulfilled",
      "buyer": {
        "buyer_id": "username123",
        "name": "John Doe",
        "phone": "111-111-1111",
        "email": "[email protected]"
      },
      "ship_to": {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US"
      },
      "tax": {
        "amount": 16.37,
        "currency": "usd"
      },
      "shipping_price": {
        "amount": 22.10,
        "currency": "usd"
      },
      "price_adjustments": [
        {
          "type": "gift_certificate",
          "amount": {
            "amount": -10,
            "currency": "usd"
          }
        },
        {
          "type": "fee",
          "amount": {
            "amount": 12,
            "currency": "usd"
          }
        }
      ],
      "total_price": {
        "amount": 115.44,
        "currency": "usd"
      },
      "payment_status": "payment_in_process",
      "payment_method": "credit_card",
      "items": [
        {
          "item_id": "9TWjnieMw6-89ypRCfY4XBGb-QsPJ9",
          "fulfillment_status": "partially_fulfilled",
          "name": "Wonder Widget",
          "sku": "KS944RUR",
          "quantity": 3,
          "weight": {
            "value": 7,
            "unit": "pound"
          },
          "unit_price": {
            "amount": 24.99,
            "currency": "usd"
          },
          "total_price": {
            "amount": 74.97,
            "currency": "usd"
          },
          "shipping_preferences": {
            "confirmation": "adult_signature",
            "expedited_service": true,
            "contains_alcohol": false,
            "delivery_date": "2020-01-20",
            "saturday_delivery": true,
            "insured_value": {
              "amount": 100,
              "currency": "usd"
            }
          },
          "links": {
            "self": "https://my-store.com/orders/123456/items/456789",
            "category": "https://my-store.com/widgets",
            "product": "https://my-store.com/product/123456",
            "image": "https://my-store.com/product/123456/image.jpg",
            "thumbnail": "https://my-store.com/product/123456/small.jpg",
            "video": "https://my-store.com/product/123456/video",
            "tracking": "https://my-store.com/orders/123456/track"
          }
        }
      ],
      "links": {
        "self": "https://my-store.com/orders/123456"
      },
      "notes": [
        {
          "type": "instructions",
          "text": "Please make sure it gets here by Dec. 22nd!"
        },
        {
          "type": "internal_notes",
          "text": "Ship by December 18th via Priority Mail."
        }
      ]
    }
  ]
}

Response Property Definitions

Name	Type	Required?	Description
`page`	int	No	The number of the current page being sent back with this response.
`pages`	int	No	The total number of pages to be expected.
`orders`	object[]	Yes	An array of objects which represent orders placed through your cart or marketplace.
`orders[].order_id`	string	Yes	The ID used by your cart or marketplace to uniquely identify this order.
`orders[].order_source_code`	string	Yes	The marketplace/order source that the order originated from.
`orders[].created_at`	date	No	The date/time that the order was placed.
`orders[].modified_at`	date	No	The date/time that this order has most recently been modified.
`orders[].status`	string	Yes	The status of the order in your system. Values: `awaiting_payment` `awaiting_shipment` `cancelled` `completed` `on_hold` `pending_fulfillment`
`orders[].fulfillment_status`	string	Yes	The fulfillment status of this order. Values: `fulfilled` `cancelled` `on_hold_per_marketplace` `partially_fulfilled` `unfulfilled` `unknown`
`orders[].buyer`	object	No	An object which holds information about the buyer of this order.
`orders[].buyer.buyer_id`	string	No	An id or username used in your cart or marketplace to identify the buyer of this order.
`orders[].buyer.name`	string	No	The name to use for billing for this buyer.
`orders[].buyer.phone`	string	No	The phone number to associate with billing for this buyer.
`orders[].buyer.email`	string	No	The email to associate with billing info for this buyer.
`orders[].ship_to`	object	Yes	An object that holds the destination address of this order.
`orders[].ship_to.name`	string	No	The name to use when shipping the order.
`orders[].ship_to.phone`	string	No	The phone number to use when shipping the order.
`orders[].ship_to.company_name`	string	No	The company to use when shipping the order.
`orders[].ship_to.address_line1`	string	Yes	Line 1 of the destination's address.
`orders[].ship_to.address_line2`	string	No	Line 2 of the destination's address.
`orders[].ship_to.city_locality`	string	Yes	The city of the destination's address.
`orders[].ship_to.state_province`	string	Yes	The state/province of the destination's address.
`orders[].ship_to.postal_code`	string	Yes	The postal code or zip code of the destination's address.
`orders[].ship_to.country_code`	string	Yes	The country code of the destination's address.
`orders[].tax`	object	Yes	An object that holds currency info for the estimated tax on this order.
`orders[].tax.currency`	string	Yes	The ISO currency code associated with this amount.
`orders[].tax.amount`	decimal	Yes	The amount of specified currency.
`orders[].shipping_price`	object	Yes	An object that holds the currency info for the adjustment amount.
`orders[].shipping_price.currency`	string	Yes	The ISO currency code associated with this amount.
`orders[].shipping_price.amount`	string	Yes	The amount of specified currency.
`orders[].total_price`	object	Yes	An object that holds the currency info for the total cost of the order.
`orders[].total_price.currency`	string	Yes	The ISO currency code associated with this amount.
`orders[].total_price.amount`	string	Yes	The amount of specified currency.
`orders[].price_adjustments`	object[]	No	An array of objects which represent adjustments to the total price which wouldn't fit into other cost fields.
`orders[].price_adjustments[].type`	string	Yes	The type of the adjustment. Values: `adjustment` `coupon` `credit` `debit` `discount` `duty` `fee` `gift_certificate` `promotion` `refund` `tariff` `tax` `other` .
`orders[].price_adjustments[].amount.currency`	string	Yes	The ISO currency code associated with this amount.
`orders[].price_adjustments[].amount.amount`	decimal	Yes	The amount of specified currency.
`orders[].payment_status`	string	Yes	The status of this order's payment. Values: `awaiting_payment` `payment_cancelled` `payment_failed` `payment_in_process` `paid` `other`
`orders[].payment_method`	string	No	The payment method used for this order.
`orders[].items`	object[]	Yes	An array of objects which each represent an item that's a part of the order.
`orders[].items[].item_id`	string	Yes	The ID used by your cart or marketplace to uniquely identify this line item on the order.
`orders[].items[].fulfillment_status`	string	Yes	The fulfillment status of this item on the order. Allowable values are the same as with the order's fulfillment status.
`orders[].items[].name`	string	Yes	The name of the product.
`orders[].items[].sku`	string	No	The SKU of the product.
`orders[].items[].quantity`	int	Yes	The number of products being sold as part of this line item.
`orders[].items[].weight`	object	No	An object that holds weight information about the product.
`orders[].items[].weight.value`	decimal	Yes	The weight of the object in the specified units.
`orders[].items[].weight.unit`	string	Yes	The unit to use when reading the weight's value. Units: `gram` `ounce` `kilogram` `pound` .
`orders[].items[].unit_price`	object	Yes	An object which holds currency information for the price per unit for this line item.
`orders[].items[].unit_price.currency`	string	Yes	The ISO currency code associated with this amount.
`orders[].items[].unit_price.amount`	decimal	Yes	The amount of specified currency.
`orders[].items[].total_price`	object	Yes	An object which holds currency information for the total for this line item.
`orders[].items[].total_price.currency`	string	Yes	The ISO currency code associated with this amount.
`orders[].items[].total_price.amount`	decimal	Yes	The amount of specified currency.
`orders[].items[].shipping_preferences`	object	No	An object that contains extra information about how this item should be shipped.
`orders[].items[].shipping_preferences.confirmation`	string	No	The type of confirmation that will be needed for this shipping item.
`orders[].items[].shipping_preferences.delivery_date`	string	No	The preferred delivery date for the shipping item. `YYYY-MM-DD` format.
`orders[].items[].shipping_preferences.expedited_service`	boolean	No	Indicates if the shipping item will be shipped using an expedited service.
`orders[].items[].shipping_preferences.contains_alcohol`	boolean	No	Indicates if the shipping item contains alcohol.
`orders[].items[].shipping_preferences.saturday_delivery`	boolean	No	Indicates if the shipping item will be a saturday delivery.
`orders[].items[].shipping_preferences.insured_value`	object	No	An object that contains information on the value that the shipping item is insured for.
`orders[].items[].shipping_preferences.insured_value.currency`	string	Yes	The ISO currency code associated with this amount.
`orders[].items[].shipping_preferences.insured_value.amount`	decimal	Yes	The amount of specified currency.
`orders[].items[].links`	object[]	No	An arry of URLs to associate with this line on the order.
`orders[].items[].links.self`	string	No	The Url location of the item being shipped in the user's custom store.
`orders[].items[].links.category`	string	No	The url location of the item's category in the user's custom store.
`orders[].items[].links.product`	string	No	The url location of the item's product description in the user's custom store.
`orders[].items[].links.image`	string	No	The url location of the item's image.
`orders[].items[].links.thumbnail`	string	No	The url location of the item's thumbnail.
`orders[].items[].links.video`	string	No	The Url location of the item's video.
`orders[].items[].links.tracking`	string	No	The Url location of the item's tracking information
`orders[].links.self`	string	No	Link to the order in the user's custom store.
`orders[].notes`	object[]	No	An array of notes to associate with the order.
`orders[].notes[].type`	string	Yes	The type of note to attach to this order. Values: `back_order_message` `condition_note` `gift_message` `internal_notes` `in_stock_message` `manufacturer_part_number` `notes_from_buyer` `notes_to_buyer` `other` `out_of_stock_message` `reason` `special_instructions` `warning_label` `feedback_message`
`orders[].notes[].text`	string	Yes	The text of the note.