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 100 |
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"
}
}
}