List Shipments

Since shipments power most of our services, we allow you to query and manage them. By querying shipments, you expose a paged service that allows you to use multiple filters.

Query Parameters	Description
batch_id	string, See warning below this table when filtering by `batch_id`
tag	string
shipment_status	`pending`, `processing`, `label_purchased`, `cancelled`
modified_at_start	date string, (ISO 8601 Standard) `2019-07-25T15:24:46.657Z`
modified_at_end	date string, (ISO 8601 Standard) `2019-07-25T15:24:46.657Z`
created_at_start	date string, (ISO 8601 Standard) `2019-07-25T15:24:46.657Z`
created_at_end	date string, (ISO 8601 Standard) `2019-07-25T15:24:46.657Z`
page	integer, defaults to 1
page_size	integer, defaults to 25
sort_dir	`asc` or `desc`
sort_by	`modified_at`, `created_at`

Warning

Filtering by Batch ID

If you filter by batch, the API will ignore shipment_status, modified_at_start, modified_at_end, created_at_start, created_at_end, and tag. The API assumes you are opening a batch to view what's in the batch queue, and batch_id is the only relevant filter since there are no other filters when executing a batch operation.

Example

GET /v1/shipments

Let's get a list of the last package we sent using the east_warehouse tag.

GET /v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

curl -iX GET 'https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Host", "api.shipengine.com")
$headers.Add("API-Key", "__YOUR_API_KEY_HERE__")

$response = Invoke-RestMethod 'https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at' -Method 'GET' -Headers $headers -Body $body
$response | ConvertTo-Json

var myHeaders = new Headers();
myHeaders.append("Host", "api.shipengine.com");
myHeaders.append("API-Key", "__YOUR_API_KEY_HERE__");

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

fetch("https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at", 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.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at',
  'headers': {
    'Host': 'api.shipengine.com',
    'API-Key': '__YOUR_API_KEY_HERE__'
  }
};
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.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at",
  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.shipengine.com",
    "API-Key: __YOUR_API_KEY_HERE__"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at"

payload = {}
headers = {
  'Host': 'api.shipengine.com',
  'API-Key': '__YOUR_API_KEY_HERE__'
}

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

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

require "uri"
require "net/http"

url = URI("https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at")

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

request = Net::HTTP::Get.new(url)
request["Host"] = "api.shipengine.com"
request["API-Key"] = "__YOUR_API_KEY_HERE__"

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

var client = new RestClient("https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Host", "api.shipengine.com");
request.AddHeader("API-Key", "__YOUR_API_KEY_HERE__");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at")
  .method("GET", null)
  .addHeader("Host", "api.shipengine.com")
  .addHeader("API-Key", "__YOUR_API_KEY_HERE__")
  .build();
Response response = client.newCall(request).execute();

package main

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

func main() {

  url := "https://api.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at"
  method := "GET"

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

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Host", "api.shipengine.com")
  req.Header.Add("API-Key", "__YOUR_API_KEY_HERE__")

  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.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.shipengine.com",
  @"API-Key": @"__YOUR_API_KEY_HERE__"
};

[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.shipengine.com/v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at")!,timeoutInterval: Double.infinity)
request.addValue("api.shipengine.com", forHTTPHeaderField: "Host")
request.addValue("__YOUR_API_KEY_HERE__", forHTTPHeaderField: "API-Key")

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()

{
  "shipments": [
    {
      "shipment_id": "se-2102034",
      "carrier_id": "",
      "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
      "ship_date": "2019-07-25T05:00:00.000Z",
      "created_at": "2019-07-25T15:24:46.657Z",
      "modified_at": "2019-07-25T15:24:46.657Z",
      "shipment_status": "pending",
      "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",
        "address_residential_indicator": "yes"
      },
      "ship_from": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "return_to": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "confirmation": "none",
      "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null,
        "non_machinable": false,
        "saturday_delivery": false
      },
      "insurance_provider": "",
      "tags": [
        {
          "name": "east_warehouse"
        }
      ],
      "total_weight": {
        "value": 9.60,
        "units": "ounce"
      },
      "packages": [
        {
          "weight": {
            "value": 9.60,
            "units": "ounce"
          },
          "dimensions": {
            "units": "inch",
            "length": 12.00,
            "width": 7.10,
            "height": 6.00
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          }
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 2,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=1&page_size=1"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
    },
    "prev": {},
    "next": {
      "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
    }
  }
}

{
  "shipments": [
    {
      "shipment_id": "se-2102034",
      "carrier_id": "",
      "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
      "ship_date": "2019-07-25T05:00:00.000Z",
      "created_at": "2019-07-25T15:24:46.657Z",
      "modified_at": "2019-07-25T15:24:46.657Z",
      "shipment_status": "pending",
      "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",
        "address_residential_indicator": "yes"
      },
      "ship_from": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "return_to": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "confirmation": "none",
      "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null,
        "non_machinable": false,
        "saturday_delivery": false
      },
      "insurance_provider": "",
      "tags": [
        {
          "name": "east_warehouse"
        }
      ],
      "total_weight": {
        "value": 9.60,
        "units": "ounce"
      },
      "packages": [
        {
          "weight": {
            "value": 9.60,
            "units": "ounce"
          },
          "dimensions": {
            "units": "inch",
            "length": 12.00,
            "width": 7.10,
            "height": 6.00
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          }
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 2,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=1&page_size=1"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
    },
    "prev": {},
    "next": {
      "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
    }
  }
}