`/shipments` endpoint¶

Use the /shipments endpoint to find and list shipments that have been imported to DropStream.

Get shipments¶

To get a sorted, filtered list of shipments and their data, make a GET request to /shipments.

Endpoint	`/shipments`
Method	`GET`
Auth	JWT
Success status	HTTP `200`
Response (JSON)	Object containing an array of shipments

Filtering¶

With no parameters, all shipments accessible to the authenticated user are returned from a GET /shipments request.

To filter shipment results, specify any of the following filter parameters:

Filter parameter	Value type	Description
`shipped_at_min`	dateString	shipped after that dateTime.
`shipped_at_max`	dateString	shipped before that dateTime.
`created_at_min`	dateString	imported to DropStream after that dateTime.
`created_at_max`	dateString	imported to DropStream before that dateTime.
`tracking_number`	string	shipment(s) with that `tracking_number`.
`store_id`	`id` (integer) or `name` (string)	shipments ordered from specified store. Note that the store name (e.g.`"Smith Appliances Shopify"`) may be specified instead of the id (e.g. `1234`).
`warehouse_id`	`id` (integer) or `name` (string)	shipped from specified warehouse. Note that the warehouse name (e.g. "`Tulsa Warehouse`") may be specified instead of the id (e.g. `1234`).
`customer_id`	`id` (integer) or `name` (string)	shipments for specified customer. Note that the customer name (e.g.`"Smith Home Appliances"`) may be specified instead of the id (e.g. `1234`).
`state`	string	shipments with specified `fulfillment_state` (DropStream internal status), e.g. "`notified_shipped`".

DateStrings in filters¶

Filter dateStrings can be specified as whole or partial ISO 8601 dateTimes, for example:

"2022-12-01T05:25:00.000Z"
"2022-12-01T00:25:00-05:00"
"2022-12-01"

DateStrings can be specified in natural language, and the API will attempt to interpret them in context. For example:

"December 1st 2022"
"dec 1"
"last monday"
"two hours ago"
"now"

Note

For precise results, specify a full ISO 8601 dateTime including calendar date, time, and zone offset.

For example, using these two filter parameters would return any shipments shipped on October 1^st in the EST (UTC-5) time zone:

shipped_at_min=2022-10-01T00:00:00-05:00&shipped_at_max=2022-10-02T00:00:00-05:00

Sorting¶

To return records sorted by ascending property value, specify sort={property}.

Sortable properties include:

tracking_number
shipped_at
created_at
warehouse_id
state

If multiple sort parameters are specified, the last one is used.

Pagination¶

Page-based results¶

If a page parameter is specified, responses will be page-based, allowing individual pages of multi-page responses to be retrieved arbitrarily by index number.

Otherwise, responses will be "session-based", returning a session ID in the first response that must be specified to retrieve subsequent results in order. Sessions expire 60 seconds after their most recent request.

The number of records returned per response is set by the optional limit parameter, with a maximum of 1000 per page (default 100).

Importantly, the total maximum results for page-based requests is 10,000. To receive more than 10,000 total results, you MUST use session-based requests. If a result set is incomplete because there were more than 10,000 total, the responses will include the field "max_total_reached":true.

Session-based results¶

If a page number is not specified, responses will be session-based, returning a session_id to be specified when requesting subsequent pages. Session-based results are returned in order starting with the first page (arbitrary pages cannot be fetched), but with unlimited maximum total results.

The number of records returned per response is set by the optional limit parameter, with a maximum of 1000 per page (default 100).

Sessions expire 60 seconds after their last request.

Examples¶

Page-based¶

Example: page-based results

Page 1 (curl)

# Get page 1 of all shipments shipped on Oct 1, 2022 
# in EST time zone (UTC -5), 

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/shipments" \
  -d "limit=100" \
  -d "page=1" \
  -d "shipped_at_min=2022-09-10T00:00:00-05:00" \
  -d "shipped_at_max=2022-09-10T23:59:59-05:00" \
  -d "sort=tracking_number"

Page 2 (curl)

# Get page 2 with the same parameters

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/shipments" \
  -d "limit=100" \
  -d "page=2" \
  -d "shipped_at_min=2022-09-10T00:00:00-05:00" \
  -d "shipped_at_max=2022-09-10T23:59:59-05:00" \
  -d "sort=tracking_number"

Response:

Page 1 (JSON)

{
  "shipments": [
    {
      "id": 75702546,
      "tracking_number": "TRACK4700650544",
      "created_at": "2022-09-10T08:28:27Z",
      "order_id": 97721881,
      "shipped_at": "2022-09-10T08:28:27Z",
      "weight": "6.0",
      "external_shipping_description": "UPS Ground",
      "carrier_name": "UPS",
      "service_level": "Ground",
      "warehouse_id": 6426,
      "state": "notified_shipped",
      "order_items": [
        {
          "id": 270322009
        }
      ]
    },
(more...)
  ],
  "page": 1,
  "limit": 100,
  "total_count": 354,
  "total_pages": 4
}

Page 2 (JSON)

{
  "shipments": [
    {
      "id": 75702644,
      "tracking_number": "TRACK7029385590",
      "created_at": "2022-09-10T12:28:30Z",
      "order_id": 97747902,
      "shipped_at": "2022-09-10T12:28:27Z",
      "weight": "8.0",
      "external_shipping_description": "UPS Ground",
      "carrier_name": "UPS",
      "service_level": "Ground",
      "warehouse_id": 6426,
      "state": "notified_shipped",
      "order_items": [
        {
          "id": 270391360
        },
        {
          "id": 270391366
        },
        {
          "id": 270391370
        }
      ]
    },
(more...)
  ],
  "page": 2,
  "limit": 100,
  "total_count": 354,
  "total_pages": 4
}

HTTP

HTTP/1.1 200 OK

Session-based¶

Example: session-based results

First page (curl)

# List all shipments shipped on Oct 1, 2022, 
# EST (UTC-5) sorted by shipped_at time.
# Response contains a session_id to be used
# in subsequent requests 

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/shipments" \
  -d "limit=100" \
  -d "shipped_at_min=2022-09-10T00:00:00-05:00" \
  -d "shipped_at_max=2022-09-10T23:59:59-05:00" \
  -d "sort=shipped_at"

Second page (curl)

# Get the next set of records from the session.
# The 60 second session timeout is refreshed. 
# Original params persist (limit, shipped_at_min .. )
# as does the session_id.

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/shipments" \
  -d "session_id=e3ed2e5b-2d5e-4f05-a9b1-6f6790996f0b"

Response:

First page (JSON)

{
  "shipments": [
    {
      "id": 75702546,
      "tracking_number": "TRACK4700650544",
      "created_at": "2022-09-10T08:28:27Z",
      "order_id": 97721881,
      "shipped_at": "2022-09-10T08:28:27Z",
      "weight": "6.0",
      "external_shipping_description": "UPS Ground",
      "carrier_name": "UPS",
      "service_level": "Ground",
      "warehouse_id": 6426,
      "state": "notified_shipped",
      "order_items": [
        {
          "id": 270322009
        }
      ]
    },
(more...)
  ],
  "session_id": "e3ed2e5b-2d5e-4f05-a9b1-6f6790996f0b",
  "page": 1,
  "limit": 100,
  "total_count": 354,
  "total_pages": 4
}

Second page (JSON)

{
  "shipments": [
    {
      "id": 75702613,
      "tracking_number": "TRACK4278515651",
      "created_at": "2022-09-10T12:28:27Z",
      "order_id": 97723071,
      "shipped_at": "2022-09-10T12:28:27Z",
      "weight": "3.0",
      "external_shipping_description": "UPS Ground",
      "carrier_name": "UPS",
      "service_level": "Ground",
      "warehouse_id": 6426,
      "state": "notified_shipped",
      "order_items": [
        {
          "id": 270325129
        }
      ]
    },
(more...)
  ],
  "session_id": "e3ed2e5b-2d5e-4f05-a9b1-6f6790996f0b",
  "page": 2,
  "limit": 100
}

HTTP

HTTP/1.1 200 OK

Get shipment with specific tracking¶

To get shipment(s) with a specific tracking number, specify filter parameter tracking_number={number}.

Example: list shipments with specific tracking

First page (curl)

# List shipments with specific tracking number

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/shipments" \
  -d "tracking_number=1Z9999999999999999"

Response:

JSON

{
  "shipments": [
    {
      "id": 75987759,
      "tracking_number": "1Z9999999999999999",
      "created_at": "2022-09-16T19:24:07Z",
      "order_id": 98131877,
      "shipped_at": "2022-09-16T19:00:22Z",
      "external_shipping_description": "UPS GROUND",
      "carrier_name": "UPS",
      "service_level": "GROUND",
      "warehouse_id": 3229,
      "state": "notified_shipped",
      "order_items": [
        {
          "id": 271524740
        }
      ]
    },
  ],
  "session_id": "e5209336-8609-48ad-a663-01779a5fae87",
  "page": 1,
  "limit": 100,
  "total_count": 1,
  "total_pages": 1
}

HTTP

HTTP/1.1 200 OK

Get shipments filtered by status¶

To get shipments in specific DropStream status, use filter parameter state={state}.

Shipment states include:

new
ready_for_shipment_notification
scheduled_notify_of_shipment
scheduled_processing_shipment
errored_processing
scheduled_notify_of_shipment
delayed_notifying_of_shipment
errored_notifying_of_shipment
notified_shipped
archived

Example: list shipments in error status

First page (curl)

# List shipments in error status

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/shipments" \
  -d "state=errored_notifying_of_shipment"

Response:

JSON

{
  "shipments": [
    {
      "id": 75721699,
      "tracking_number": "TRACK2228441738",
      "created_at": "2022-09-11T16:28:28Z",
      "order_id": 97787184,
      "shipped_at": "2022-09-11T16:28:27Z",
      "weight": "6.0",
      "external_shipping_description": "UPS Ground",
      "carrier_name": "UPS",
      "service_level": "Ground",
      "warehouse_id": 6426,
      "state": "errored_notifying_of_shipment",
      "order_items": [
        {
          "id": 270473909
        }
      ]
    },
(more...)
  ],
  "session_id": "e5209336-8609-48ad-a663-01779a5fae87",
  "page": 1,
  "limit": 100,
  "total_count": 42,
  "total_pages": 1
}

HTTP

HTTP/1.1 200 OK

/shipments endpoint¶

Get shipments¶

Filtering¶

DateStrings in filters¶

Sorting¶

Pagination¶

Page-based results¶

Session-based results¶

Examples¶

Page-based¶

Session-based¶

Get shipment with specific tracking¶

Get shipments filtered by status¶

`/shipments` endpoint¶