Manage shipments

Get shipments

Retrieving one or multiple shipments in the API uses the same flexible GET /v2/shipments shipment list endpoint that supports querying for a shipment or shipments. Obtaining one or more shipments will follow the same paginated data access pattern and only vary in the number of results returned in the API response from your request. The GET /v2/shipments API route or endpoint parameters are documented here in the API reference.

The base API call to get a paginated list of shipments is:

Example shipments list query request

About This Request Payload

The example below is default query for the GET /v2/shipments shipment list endpoint . You may specify additional query/querystring parameters to filter, sort, change the number of items returned, etc.
Set the page-size query parameter to set the maximum number of items returned in the response (i.e. ?page-size=25 , ?existing_param=abc&page-size=50 ).
Set the ordering parameter to sort the data/items by a particular property value (i.e. ?ordering=created_at , ?page-size=20&ordering=status ).
Add a - (minus sign) to the ordering parameter value to sort by that parameter in descending sort order instead of the default ascending sort order (i.e. ?ordering=-created_at , ?page-size=20&ordering=-created_at ).
The default sort order of shipments is based on the date they were created, starting with the latest shipment (aka descending sort order by created_at date/time).
Shipwell only responds with shipments for the company associated with the API key, token, or user making the request.
See the shipment list API reference for a detailed list of fields or properties for the request and response bodies for shipment listing/querying.
To include archived shipments in the query results, set the archived query parameter (see these steps ).

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/v2/shipments' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const basePath = "/v2";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/shipments`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/shipments"

headers = {
    "Accept-Type": "application/json",
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

response = requests.get(target_url, headers=headers)
data = response.json()
print(data)

Example shipments list query response

Copy

Copied

{
  "results": [
      {
        "id":"caaad729-4b6f-49bf-8f93-b9f3de73b6e8",
        "reference_id": "SK799X",
        // ...
      },
    // ... other shipments ...
  ],
  "page-size": 10,
  "total_pages": 100, // number of pages of items based on the page size
  "total_count": 1000 // number of total items that match the query (including the items outside the current page of items/results)
}

Get one specific shipment

Retrieve the details of an existing shipment by the specific and unique shipment id.

Tip

You may also get or retrieve an existing shipment by the reference_id using GET /v2/shipments?reference_id=YOUR_REFERENCE_ID_OR_NUMBER using the shipment list/query endpoint. In certain use cases, this is preferred to the shipment id of the shipment since the reference often functions as an alias to a shipment as it is a reference set/generated by you or your systems. If the shipment is potentially archived see this note on querying for archived shipments.

Example get one specific shipment request

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/v2/shipments/{shipmentId}' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const shipmentId = "YOUR_shipmentId_PARAMETER";
const basePath = "/v2";
const host = "sandbox-api.shipwell.com";

const query = new URLSearchParams({
  id: shipmentId,
}).toString();

const resp = await fetch(
  `https://${host}${basePath}/shipments/{$shipmentId}`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

shipment_id = "YOUR_shipmentId_PARAMETER"
base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/shipments/" + shipment_id

headers = {
    "Accept-Type": "application/json",
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

response = requests.get(target_url, headers=headers)
data = response.json()
print(data)

Example get one specific shipment response

Copy

Copied

{
    "id": "caaad729-4b6f-49bf-8f93-b9f3de73b6e8",
    "auction_stats": {
        "negotiations": 0,
        "quotes": 0,
        "declined_quotes": 0,
        "messages": 0,
        "most_recent_quote_created_at": null,
        "visible_companies": 0,
        "lowest_bid": null
    },
    "current_carrier": null,
    "customer": {
        "id": "6c6d1cef-580d-472d-9458-c03d84ea4bd1",
        "name": "Shipwell Sandbox",
        "dba_name": null,
        "is_shipwell": false,
        "created_at": "2020-02-21T00:31:36.935076Z",
        "updated_at": "2020-03-19T18:10:22.812172Z",
        "brokerage": "11aadf34-c2a2-4b26-9032-2ab8e4c068e7",
        "shipper": null,
        "carrier": null,
        "primary_email": "kenny+test@shipwell.com",
        "billing_email": "greg+sandbox@shipwell.com",
        "billing_emails": null
    },
    "documents_count": 0,
    "equipment_type": {
        "id": 1,
        "name": "Dry Van",
        "machine_readable": "DRY_VAN"
    },
    "external_tracking_link": "https://sandbox.shipwell.com/tracking/caaad729-4b6f-49bf-8f93-b9f3de73b6e8/?key=ORaW7Q3ZsonlBBEIRM3zTOgWeYtmAhsm",
    "line_items": [
        {
            "id": "27d186cf-2ffa-4d6f-96ce-e20848ae1eca",
            "formatted_description": "68,900 lb (31,252.51429 kg), Paper Clips",
            "insured_value": null,
            "value_per_piece": null,
            "deleted_at": null,
            "created_at": "2020-08-26T17:07:24.503043Z",
            "updated_at": "2020-08-26T17:07:24.503915Z",
            "custom_data": null,
            "piece_type": null,
            "package_type": null,
            "freight_class": null,
            "provider_specific_packaging": null,
            "nmfc_item_code": null,
            "nmfc_sub_code": null,
            "stackable": true,
            "hazmat_hazard_class": null,
            "hazmat_identification_number": null,
            "hazmat_proper_shipping_name": null,
            "hazmat_packing_group": null,
            "height": 45,
            "length": 45,
            "width": 45,
            "length_unit": "IN",
            "value_per_piece_currency": "USD",
            "package_weight": 6890.0,
            "weight_unit": "LB",
            "refrigeration_required": false,
            "refrigeration_min_temp": null,
            "refrigeration_max_temp": null,
            "temp_unit": "F",
            "country_of_manufacture": null,
            "product_ref": null,
            "description": "Paper Clips",
            "total_packages": 10,
            "total_pieces": null,
            "insured_value_currency": "USD",
            "dry_ice_weight": null,
            "dry_ice_weight_unit": "LB",
            "purchase_order": null
        }
    ],
    "markup": null,
    "metadata": {
        "open": true,
        "archived": false,
        "tags": ["add27dc9-0745-4f1a-a551-1b06b47ccf1b"],
        "alert_level": null,
        "alert_message": null,
        "automation_enabled": false,
        "max_buy_amount": null,
        "max_buy_amount_currency": "USD",
        "bill_to_override": {
            "company_address": "4410 Duval Rd, Austin, TX 78727, US",
            "company_name": "Shipwell",
            "contact_email": "fn2@g.com",
            "contact_phone": "+14752239082",
            "direction": "3RD_PARTY"
        },
        "load_board_enabled": false,
        "buy_it_now_amount": null,
        "buy_it_now_amount_currency": "USD",
        "load_board_id": "LIDPMGQC7",
        "has_open_auction": false,
        "pending_tender_acceptance": false,
        "custom_reference_values": [
            {
                "id": "f1de337b-75fc-4156-839f-ddc5bf517049",
                "value": null,
                "custom_reference": "0190f928-9b6a-4553-a50c-3633376a3bb3",
                "custom_reference_name": "Priority"
            }
        ]
    },
    "mode": {
        "id": 1,
        "code": "FTL",
        "description": "Full Truckload"
    },
    "next_planned_stop_id": "d4a02943-8c1a-4ffd-9397-cc5bda2825bc",
    "notes_count": 0,
    "parcel_pickup_status": null,
    "service_level": {
        "id": 19,
        "code": "STD",
        "description": "Standard Service"
    },
    "state": "draft",
    "stops": [
        {
            "id": "d4a02943-8c1a-4ffd-9397-cc5bda2825bc",
            "location": {
                "id": "49338b99-04c8-4aad-af25-3fa839ac9711",
                "point_of_contacts": [
                    {
                        "id": "a0a2c12c-788b-4cda-8e88-cee8c1078001",
                        "full_name": "Nathaniel Archer",
                        "preferences": {
                            "cancellation": false,
                            "delayed": false,
                            "delivered": false,
                            "eta_changed": false,
                            "picked_up": false,
                            "receive_bol_on_shipment_booked": false,
                            "shipment_booked": false
                        },
                        "created_at": "2020-08-26T17:07:23.858262Z",
                        "updated_at": "2020-08-26T17:07:23.859233Z",
                        "first_name": "Nathaniel",
                        "last_name": "Archer",
                        "job_title": null,
                        "phone_number": "+15122335667",
                        "email": "nathaniel.archer@shipwell.com"
                    }
                ],
                "address": {
                    "id": "475556e2-3a4e-48bb-98bc-ee1b87a822ea",
                    "formatted_address": "515 Congress Ave, Austin, TX 78701, US",
                    "created_at": "2020-08-26T17:07:23.248985Z",
                    "updated_at": "2020-08-26T17:07:23.849520Z",
                    "address_1": "515 Congress Ave",
                    "address_2": null,
                    "city": "Austin",
                    "state_province": "TX",
                    "postal_code": "78701",
                    "country": "US",
                    "phone_number": null,
                    "timezone": "America/Chicago",
                    "latitude": 30.2677416,
                    "longitude": -97.7426039
                },
                "location_type": {
                    "id": 1,
                    "name": "Business (with dock or forklift)"
                },
                "identification_code": null,
                "created_at": "2020-08-26T17:07:23.851322Z",
                "updated_at": "2020-08-26T17:07:23.852220Z",
                "custom_data": null,
                "location_name": "Pickup Company",
                "company_name": null,
                "dock_hours_start": null,
                "dock_hours_end": null,
                "dock_external_id": null,
                "notes": null
            },
            "accessorials": [],
            "appointment_type": null,
            "carrier_specified_eta": {
                "created_at": "2020-08-26T17:07:23.861044Z",
                "updated_at": "2020-08-26T17:07:23.862154Z",
                "initial_window_start": null,
                "initial_window_end": null,
                "running_window_start": null,
                "running_window_end": null,
                "overridden_initial_window_start": null,
                "overridden_initial_window_end": null
            },
            "predictive_model_eta": {
                "created_at": "2020-08-26T17:07:23.864032Z",
                "updated_at": "2020-08-26T17:07:23.865235Z",
                "initial_window_start": null,
                "initial_window_end": null,
                "running_window_start": null,
                "running_window_end": null,
                "overridden_initial_window_start": null,
                "overridden_initial_window_end": null
            },
            "display_eta_window": "Thu Dec 24, 08:00-10:00 CST",
            "display_planned_window": "Thu Dec 24, 08:00-10:00 CST",
            "display_schedule": "Thu Dec 24 between 08:00-10:00 CST",
            "created_at": "2020-08-26T17:07:23.860579Z",
            "updated_at": "2020-08-26T17:07:23.868389Z",
            "planned_date": "2020-12-24",
            "planned_time_window_start": "08:00:00",
            "planned_time_window_end": "10:00:00",
            "confirmed_arrival_at": null,
            "confirmed_departure_at": null,
            "unconfirmed_arrival_at": null,
            "unconfirmed_departure_at": null,
            "ordinal_index": 0,
            "is_pickup": true,
            "is_dropoff": false,
            "on_time": null,
            "exclude_on_time": true,
            "on_time_exclusion_reason": null,
            "instructions": null,
            "internal_notes": null,
            "driver_pickup_confirmation_initial_job_id": null,
            "driver_pickup_confirmation_no_response_job_id": null,
            "driver_stop_completion_initial_job_id": null,
            "driver_stop_completion_second_job_id": null,
            "driver_stop_completion_no_response_job_id": null,
            "driver_stop_completion_enter_no_exit_geofence_job_id": null,
            "driver_stop_completion_never_enter_geofence_job_id": null,
            "status": null,
            "status_reason_code": null,
            "eta_overridden_by": null
        },
        {
            "id": "d08718c4-77b4-43c7-8075-c62c317b4716",
            "location": {
                "id": "95f96beb-5a44-43e9-a7ba-47dea6dfeb54",
                "point_of_contacts": [
                    {
                        "id": "1ddb1055-d7b2-4745-8e28-27152d26240f",
                        "full_name": "Nathaniel Archer",
                        "preferences": {
                            "cancellation": false,
                            "delayed": false,
                            "delivered": false,
                            "eta_changed": false,
                            "picked_up": false,
                            "receive_bol_on_shipment_booked": false,
                            "shipment_booked": false
                        },
                        "created_at": "2020-08-26T17:07:24.406975Z",
                        "updated_at": "2020-08-26T17:07:24.408488Z",
                        "first_name": "Nathaniel",
                        "last_name": "Archer",
                        "job_title": null,
                        "phone_number": "+15122335668",
                        "email": "nathaniel.archer3@shipwell.com"
                    }
                ],
                "address": {
                    "id": "255ad837-77f0-4cd0-8992-8e65f4168620",
                    "formatted_address": "5100 Congress Ave, Austin, TX 78701, US",
                    "created_at": "2020-08-26T17:07:23.970160Z",
                    "updated_at": "2020-08-26T17:07:24.393264Z",
                    "address_1": "5100 Congress Ave",
                    "address_2": null,
                    "city": "Austin",
                    "state_province": "TX",
                    "postal_code": "78701",
                    "country": "US",
                    "phone_number": null,
                    "timezone": "America/Chicago",
                    "latitude": 30.2718005,
                    "longitude": -97.7414332
                },
                "location_type": {
                    "id": 1,
                    "name": "Business (with dock or forklift)"
                },
                "identification_code": null,
                "created_at": "2020-08-26T17:07:24.395323Z",
                "updated_at": "2020-08-26T17:07:24.396763Z",
                "custom_data": null,
                "location_name": "Dropoff Company",
                "company_name": null,
                "dock_hours_start": null,
                "dock_hours_end": null,
                "dock_external_id": null,
                "notes": null
            },
            "accessorials": [],
            "appointment_type": null,
            "carrier_specified_eta": {
                "created_at": "2020-08-26T17:07:24.410819Z",
                "updated_at": "2020-08-26T17:07:24.412472Z",
                "initial_window_start": null,
                "initial_window_end": null,
                "running_window_start": null,
                "running_window_end": null,
                "overridden_initial_window_start": null,
                "overridden_initial_window_end": null
            },
            "predictive_model_eta": {
                "created_at": "2020-08-26T17:07:24.415313Z",
                "updated_at": "2020-08-26T17:07:24.416991Z",
                "initial_window_start": null,
                "initial_window_end": null,
                "running_window_start": null,
                "running_window_end": null,
                "overridden_initial_window_start": null,
                "overridden_initial_window_end": null
            },
            "display_eta_window": "Fri Dec 25, 08:00-10:00 CST",
            "display_planned_window": "Fri Dec 25, 08:00-10:00 CST",
            "display_schedule": "Fri Dec 25 between 08:00-10:00 CST",
            "created_at": "2020-08-26T17:07:24.410213Z",
            "updated_at": "2020-08-26T17:07:24.421664Z",
            "planned_date": "2020-12-25",
            "planned_time_window_start": "08:00:00",
            "planned_time_window_end": "10:00:00",
            "confirmed_arrival_at": null,
            "confirmed_departure_at": null,
            "unconfirmed_arrival_at": null,
            "unconfirmed_departure_at": null,
            "ordinal_index": 1,
            "is_pickup": false,
            "is_dropoff": true,
            "on_time": null,
            "exclude_on_time": true,
            "on_time_exclusion_reason": null,
            "instructions": null,
            "internal_notes": null,
            "driver_pickup_confirmation_initial_job_id": null,
            "driver_pickup_confirmation_no_response_job_id": null,
            "driver_stop_completion_initial_job_id": null,
            "driver_stop_completion_second_job_id": null,
            "driver_stop_completion_no_response_job_id": null,
            "driver_stop_completion_enter_no_exit_geofence_job_id": null,
            "driver_stop_completion_never_enter_geofence_job_id": null,
            "status": null,
            "status_reason_code": null,
            "eta_overridden_by": null
        }
    ],
    "timeline_last_updated_at": null,
    "total_miles": null,
    "total_weight_override": {
        "value": null,
        "unit": "LB"
    },
    "shipment_pickup": null,
    "fedex_specific_options": null,
    "ups_specific_options": null,
    "usps_specific_options": null,
    "current_address": {
        "id": "c953cd68-8613-480a-879d-dbdac9d3b820",
        "created_at": "2020-08-26T17:07:25.491949Z",
        "updated_at": "2020-08-26T17:07:25.493557Z",
        "address_1": null,
        "address_2": null,
        "city": null,
        "state_province": null,
        "postal_code": null,
        "country": "",
        "phone_number": null,
        "timezone": null,
        "latitude": null,
        "longitude": null,
        "reported_at": null,
        "shipment": "caaad729-4b6f-49bf-8f93-b9f3de73b6e8"
    },
    "relationship_to_customer": {
        "id": "35d574cf-1f2d-405c-bc9b-97959aa12a05",
        "created_at": "2020-08-26T17:07:24.852699Z",
        "vendor": {
            "id": "6c6d1cef-580d-472d-9458-c03d84ea4bd1",
            "name": "Shipwell Sandbox",
            "dba_name": null,
            "primary_phone_number": "+12345678901",
            "primary_email": "kenny+test@shipwell.com",
            "mailing_address": {
                "id": "cb32702e-85fc-4073-afdd-ffeae16995b6",
                "address_1": "515 Congress Ave",
                "address_2": "Unit 2650",
                "city": "Austin",
                "state_province": "TX",
                "postal_code": "78701",
                "country": "US",
                "phone_number": null,
                "latitude": 30.2677416,
                "longitude": -97.7426039,
                "timezone": "America/Chicago",
                "formatted_address": "515 Congress Ave Unit 2650, Austin, TX 78701, US",
                "created_at": "2020-03-19T15:09:13.901434Z",
                "updated_at": "2020-03-19T18:10:22.770122Z"
            },
            "billing_address": {
                "id": "e8b486bb-9f6f-49b5-a9a2-bb8d68db8e36",
                "address_1": "515 Congress Ave",
                "address_2": "Unit 2650",
                "city": "Austin",
                "state_province": "TX",
                "postal_code": "78701",
                "country": "US",
                "phone_number": null,
                "latitude": 30.2677416,
                "longitude": -97.7426039,
                "timezone": "America/Chicago",
                "formatted_address": "515 Congress Ave Unit 2650, Austin, TX 78701, US",
                "created_at": "2020-03-19T15:09:13.906869Z",
                "updated_at": "2020-03-19T18:10:22.778053Z"
            },
            "identifying_codes": [
                {
                    "id": "04ee2ebd-0dcd-4083-853d-e082e51b7d4f",
                    "type": "USDOT",
                    "value": "123351",
                    "created_at": "2020-03-19T18:10:22.796772Z",
                    "updated_at": "2020-03-19T18:10:22.797273Z"
                },
                {
                    "id": "23d61cb1-af0e-449d-a16d-6deec1a83900",
                    "type": "SCAC",
                    "value": "BEST1",
                    "created_at": "2020-03-19T18:10:22.806397Z",
                    "updated_at": "2020-03-19T18:10:22.806831Z"
                }
            ],
            "created_at": "2020-02-21T00:31:36.935076Z",
            "updated_at": "2020-03-19T18:10:22.812172Z",
            "brokerage": {
                "id": "11aadf34-c2a2-4b26-9032-2ab8e4c068e7",
                "dba_name": null,
                "primary_phone_number": null,
                "primary_email": null,
                "mailing_address": null,
                "billing_address": null,
                "created_at": "2020-02-21T00:31:36.955969Z",
                "updated_at": "2020-03-19T18:10:22.785555Z",
                "is_3pl": false
            },
            "shipper": null,
            "carrier": null,
            "feature_flags": {
                "company": "6c6d1cef-580d-472d-9458-c03d84ea4bd1",
                "datadocks_enabled": false,
                "can_book_manual_shipments": true,
                "can_initiate_mobile_ping_tracking": false,
                "can_override_bill_to_for_automated_ltl": false,
                "purchase_orders_enabled": true,
                "analytics_enabled": false,
                "uses_3pl_quoting_flow": true,
                "carrier_prioritization_enabled": false,
                "invoicing_enabled": false,
                "load_board_enabled": true,
                "show_load_board": true,
                "credit_limit_enabled": true,
                "integrations_enabled": false,
                "fedex_enabled": false,
                "ftl_instant_rates_enabled": false,
                "supplier_invites_enabled": true,
                "triumph_pay_enabled": false,
                "ups_enabled": false,
                "freightwaves_driver_texts_enabled": false,
                "new_dashboard_enabled": true,
                "contracts_enabled": true,
                "usps_enabled": false,
                "historical_pricing_enabled": true,
                "policies_enabled": true,
                "rmis_enabled": false,
                "send_shipwell_network_enabled": true,
                "bid_manager_enabled": false,
                "ch_robinson_enabled": false,
                "edi_invoicing_enabled": false,
                "netsuite_enabled": false,
                "stop_status_enabled": false
            },
            "billing_email": "greg+sandbox@shipwell.com",
            "billing_emails": null,
            "insurance_expires_at": null,
            "insurance_validated_at": null,
            "insurance_policy_number": null,
            "insurance_provider_name": null,
            "insurance_provider_phone": null,
            "is_shipwell": false,
            "custom_data": null
        },
        "customer": {
            "id": "6c6d1cef-580d-472d-9458-c03d84ea4bd1",
            "name": "Shipwell Sandbox",
            "dba_name": null,
            "primary_phone_number": "+12345678901",
            "primary_email": "kenny+test@shipwell.com",
            "mailing_address": {
                "id": "cb32702e-85fc-4073-afdd-ffeae16995b6",
                "address_1": "515 Congress Ave",
                "address_2": "Unit 2650",
                "city": "Austin",
                "state_province": "TX",
                "postal_code": "78701",
                "country": "US",
                "phone_number": null,
                "latitude": 30.2677416,
                "longitude": -97.7426039,
                "timezone": "America/Chicago",
                "formatted_address": "515 Congress Ave Unit 2650, Austin, TX 78701, US",
                "created_at": "2020-03-19T15:09:13.901434Z",
                "updated_at": "2020-03-19T18:10:22.770122Z"
            },
            "billing_address": {
                "id": "e8b486bb-9f6f-49b5-a9a2-bb8d68db8e36",
                "address_1": "515 Congress Ave",
                "address_2": "Unit 2650",
                "city": "Austin",
                "state_province": "TX",
                "postal_code": "78701",
                "country": "US",
                "phone_number": null,
                "latitude": 30.2677416,
                "longitude": -97.7426039,
                "timezone": "America/Chicago",
                "formatted_address": "515 Congress Ave Unit 2650, Austin, TX 78701, US",
                "created_at": "2020-03-19T15:09:13.906869Z",
                "updated_at": "2020-03-19T18:10:22.778053Z"
            },
            "identifying_codes": [
                {
                    "id": "04ee2ebd-0dcd-4083-853d-e082e51b7d4f",
                    "type": "USDOT",
                    "value": "123351",
                    "created_at": "2020-03-19T18:10:22.796772Z",
                    "updated_at": "2020-03-19T18:10:22.797273Z"
                },
                {
                    "id": "23d61cb1-af0e-449d-a16d-6deec1a83900",
                    "type": "SCAC",
                    "value": "BEST1",
                    "created_at": "2020-03-19T18:10:22.806397Z",
                    "updated_at": "2020-03-19T18:10:22.806831Z"
                }
            ],
            "created_at": "2020-02-21T00:31:36.935076Z",
            "updated_at": "2020-03-19T18:10:22.812172Z",
            "brokerage": {
                "id": "11aadf34-c2a2-4b26-9032-2ab8e4c068e7",
                "dba_name": null,
                "primary_phone_number": null,
                "primary_email": null,
                "mailing_address": null,
                "billing_address": null,
                "created_at": "2020-02-21T00:31:36.955969Z",
                "updated_at": "2020-03-19T18:10:22.785555Z",
                "is_3pl": false
            },
            "shipper": null,
            "carrier": null,
            "feature_flags": {
                "company": "6c6d1cef-580d-472d-9458-c03d84ea4bd1",
                "datadocks_enabled": false,
                "can_book_manual_shipments": true,
                "can_initiate_mobile_ping_tracking": false,
                "can_override_bill_to_for_automated_ltl": false,
                "purchase_orders_enabled": true,
                "analytics_enabled": false,
                "uses_3pl_quoting_flow": true,
                "carrier_prioritization_enabled": false,
                "invoicing_enabled": false,
                "load_board_enabled": true,
                "show_load_board": true,
                "credit_limit_enabled": true,
                "integrations_enabled": false,
                "fedex_enabled": false,
                "ftl_instant_rates_enabled": false,
                "supplier_invites_enabled": true,
                "triumph_pay_enabled": false,
                "ups_enabled": false,
                "freightwaves_driver_texts_enabled": false,
                "new_dashboard_enabled": true,
                "contracts_enabled": true,
                "usps_enabled": false,
                "historical_pricing_enabled": true,
                "policies_enabled": true,
                "rmis_enabled": false,
                "send_shipwell_network_enabled": true,
                "bid_manager_enabled": false,
                "ch_robinson_enabled": false,
                "edi_invoicing_enabled": false,
                "netsuite_enabled": false,
                "stop_status_enabled": false
            },
            "billing_email": "greg+sandbox@shipwell.com",
            "billing_emails": null,
            "insurance_expires_at": null,
            "insurance_validated_at": null,
            "insurance_policy_number": null,
            "insurance_provider_name": null,
            "insurance_provider_phone": null,
            "is_shipwell": false,
            "custom_data": null
        },
        "customer_charge_line_items": [],
        "vendor_charge_line_items": [],
        "is_assigned_carrier": false,
        "vendor_point_of_contact": null,
        "send_point_of_contact_email": false
    },
    "relationship_to_vendor": null,
    "accessorials": [],
    "equipment_config": null,
    "most_recently_awarded_quote_id": null,
    "most_recently_awarded_tender_id": null,
    "most_recently_awarded_quote": null,
    "most_recently_awarded_tender": null,
    "next_planned_stop": {
        "id": "d4a02943-8c1a-4ffd-9397-cc5bda2825bc",
        "location": {
            "id": "49338b99-04c8-4aad-af25-3fa839ac9711",
            "point_of_contacts": [
                {
                    "id": "a0a2c12c-788b-4cda-8e88-cee8c1078001",
                    "full_name": "Nathaniel Archer",
                    "preferences": {
                        "cancellation": false,
                        "delayed": false,
                        "delivered": false,
                        "eta_changed": false,
                        "picked_up": false,
                        "receive_bol_on_shipment_booked": false,
                        "shipment_booked": false
                    },
                    "created_at": "2020-08-26T17:07:23.858262Z",
                    "updated_at": "2020-08-26T17:07:23.859233Z",
                    "first_name": "Nathaniel",
                    "last_name": "Archer",
                    "job_title": null,
                    "phone_number": "+15122335667",
                    "email": "nathaniel.archer@shipwell.com"
                }
            ],
            "address": {
                "id": "475556e2-3a4e-48bb-98bc-ee1b87a822ea",
                "formatted_address": "515 Congress Ave, Austin, TX 78701, US",
                "created_at": "2020-08-26T17:07:23.248985Z",
                "updated_at": "2020-08-26T17:07:23.849520Z",
                "address_1": "515 Congress Ave",
                "address_2": null,
                "city": "Austin",
                "state_province": "TX",
                "postal_code": "78701",
                "country": "US",
                "phone_number": null,
                "timezone": "America/Chicago",
                "latitude": 30.2677416,
                "longitude": -97.7426039
            },
            "location_type": {
                "id": 1,
                "name": "Business (with dock or forklift)"
            },
            "identification_code": null,
            "created_at": "2020-08-26T17:07:23.851322Z",
            "updated_at": "2020-08-26T17:07:23.852220Z",
            "custom_data": null,
            "location_name": "Pickup Company",
            "company_name": null,
            "dock_hours_start": null,
            "dock_hours_end": null,
            "dock_external_id": null,
            "notes": null
        },
        "accessorials": [],
        "appointment_type": null,
        "carrier_specified_eta": {
            "created_at": "2020-08-26T17:07:23.861044Z",
            "updated_at": "2020-08-26T17:07:23.862154Z",
            "initial_window_start": null,
            "initial_window_end": null,
            "running_window_start": null,
            "running_window_end": null,
            "overridden_initial_window_start": null,
            "overridden_initial_window_end": null
        },
        "predictive_model_eta": {
            "created_at": "2020-08-26T17:07:23.864032Z",
            "updated_at": "2020-08-26T17:07:23.865235Z",
            "initial_window_start": null,
            "initial_window_end": null,
            "running_window_start": null,
            "running_window_end": null,
            "overridden_initial_window_start": null,
            "overridden_initial_window_end": null
        },
        "display_eta_window": "Thu Dec 24, 08:00-10:00 CST",
        "display_planned_window": "Thu Dec 24, 08:00-10:00 CST",
        "display_schedule": "Thu Dec 24 between 08:00-10:00 CST",
        "created_at": "2020-08-26T17:07:23.860579Z",
        "updated_at": "2020-08-26T17:07:23.868389Z",
        "planned_date": "2020-12-24",
        "planned_time_window_start": "08:00:00",
        "planned_time_window_end": "10:00:00",
        "confirmed_arrival_at": null,
        "confirmed_departure_at": null,
        "unconfirmed_arrival_at": null,
        "unconfirmed_departure_at": null,
        "ordinal_index": 0,
        "is_pickup": true,
        "is_dropoff": false,
        "on_time": null,
        "exclude_on_time": true,
        "on_time_exclusion_reason": null,
        "instructions": null,
        "internal_notes": null,
        "driver_pickup_confirmation_initial_job_id": null,
        "driver_pickup_confirmation_no_response_job_id": null,
        "driver_stop_completion_initial_job_id": null,
        "driver_stop_completion_second_job_id": null,
        "driver_stop_completion_no_response_job_id": null,
        "driver_stop_completion_enter_no_exit_geofence_job_id": null,
        "driver_stop_completion_never_enter_geofence_job_id": null,
        "status": null,
        "status_reason_code": null,
        "eta_overridden_by": null
    },
    "rfqs": [],
    "state_updated_at": "2020-08-26T17:07:23.144539Z",
    "timeline_events": [],
    "additional_bol_recipients": [],
    "total_declared_value": null,
    "custom_data": null,
    "deleted_at": null,
    "created_at": "2020-08-26T17:07:23.134376Z",
    "updated_at": "2020-08-26T17:07:24.777631Z",
    "reference_id": "SK799X",
    "group_id": null,
    "name": null,
    "created_by_source": "SHIPWELL_WEB",
    "est_trip_miles": null,
    "final_trip_miles": null,
    "total_linear_feet": null,
    "description": null,
    "significantly_modified_at": null,
    "label_last_printed_at": null,
    "temperature_upper_limit": null,
    "temperature_lower_limit": null,
    "cancellation_reason": null,
    "delayed": false,
    "notes_for_carrier": "Driver check-in at front gate",
    "preferred_currency": "USD",
    "bol_number": "SW12345",
    "customer_reference_number": "TEST-SHIPMENT",
    "pickup_number": "PU-123",
    "pro_number": null,
    "purchase_order_number": "TEST-PO",
    "capacity_provider_customer_reference_number": null,
    "tracking_number": null,
    "total_declared_value_currency": "USD",
    "drayage_estimated_arrival_date": null,
    "drayage_release_date": null,
    "drayage_last_free_date": null,
    "drayage_container_return_date": null,
    "drayage_booking_number": null,
    "drayage_chassis_number": null,
    "drayage_container_number": null,
    "drayage_seal_number": null,
    "created_by_user": "2fd8c238-05d4-42b2-90a7-2341de37eb73",
    "dispatch_jobs": [
        {
            "created_at": "2020-08-26T17:07:23.134376Z",
            "error_message": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "status": "PROCESSING"
        }
    ]
}

Get multiple shipments

Obtaining multiple shipments is purposefully similar to obtaining a single order. You may combine various search or query criteria to filter orders and apply an ordering querystring parameter if you which to sort the shipments by a particular property on the shipment.

Set page-size querystring parameter in the request to restrict the number of results returned from the shipment request. Example: /v2/shipments?page-size=10 .
Set the page querystring parameter in the request to select a specific page of results (i.e. if there are 20 total items, total_count is 20 in the response body, that match the query and the page-size is 10 then /v2/shipments?page-size=10&page=2 would return the second page of results which are items 11-20 )
When querying for shipments by date/times, use the UTC time zone instead of a local time zone.
Date/times are represented as ISO 8601 date/time strings in the UTC time zone (a Z or +00:00 at the end of the date/time string is the indicator for UTC ).
See the shipment list API reference for a detailed list of fields or properties for the request and response structures for this operation.
To include archived shipments in the query results, set the archived query parameter (see these steps ).

Example get multiple shipments request

About This Request

This is an example of querying for shipments with a shipment status or state of at_pickup .
See the list of shipment statuses (strings)
You may also request code samples in other programming languages by utilizing Shipwell's AI-powered developer chatbot on the developer portal. Ask the chatbot to "Translate the following code sample into programming language X." where X is your desired programming language.

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/v2/shipments?status=at_pickup&page-size=100' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const statusParam = "YOUR_status_PARAMETER";
const basePath = "/v2";
const host = "sandbox-api.shipwell.com";

const urlSearchParams = new URLSearchParams({
  "page-size": 100,
  "status": statusParam
  // ... other parameters
});

const resp = await fetch(
  `https://${host}${basePath}/shipments?${query}`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

status_param = "YOUR_status_PARAMETER"
base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/shipments"

headers = {
    "Accept-Type": "application/json",
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

query_params = {
    "status": status_param,
    "page-size": 100
}

response = requests.get(target_url, headers=headers, params=query_params)
data = response.json()
print(data)

Example get multiple shipments request with pagination helper (advanced)

About This Request

This example demonstrates a more robust way to handle pagination with the Shipwell API using helper functions.
The pagination helper provides utilities for:
- Fetching specific pages
- Getting all pages of results
- Changing page size
- Managing sorting order
- Error handling and type safety
You may also request code samples in other programming languages by utilizing Shipwell's AI-powered developer chatbot on the developer portal. Ask the chatbot to "Translate the following code sample into programming language X." where X is your desired programming language.

Copy

Copied

from typing import Dict, List, Any
from dataclasses import dataclass, field
import requests
from datetime import datetime
@dataclass
class ShipwellPaginationConfigV2:
    """Configuration class for Shipwell API pagination (v2)"""
    base_path: str = "/v2"
    host: str = "sandbox-api.shipwell.com"
    status: str = ""
    page_size: int = 100
    ordering: List[str] = field(default_factory=list)
    def get_query_params(self) -> Dict[str, Any]:
        """Generate query parameters for API request"""
        params = {
            "status": self.status,
            "page-size": self.page_size
        }
        if self.ordering:
            params["ordering"] = ",".join(self.ordering)
        return params

def get_shipments(
    headers: Dict[str, str],
    config: ShipwellPaginationConfigV2,
    page: int = 1
) -> Dict[str, Any]:
    """
    Get shipments with pagination
    
    Args:
        headers: Request headers including Authorization
        config: Pagination configuration
        page: Page number to fetch
    
    Returns:
        API response as dictionary
    """
    target_url = f"https://{config.host}{config.base_path}/shipments"
    
    # Add page number to query parameters
    query_params = config.get_query_params()
    query_params["page"] = page
    
    response = requests.get(
        target_url,
        headers=headers,
        params=query_params
    )
    response.raise_for_status()
    return response.json()

def get_all_shipments(
    headers: Dict[str, str],
    config: ShipwellPaginationConfigV2
) -> List[Dict[str, Any]]:
    """
    Get all shipments by iterating through all pages
    
    Args:
        headers: Request headers including Authorization
        config: Pagination configuration
    
    Returns:
        List of all shipment results
    """
    all_results = []
    current_page = 1
    
    while True:
        response = get_shipments(headers, config, current_page)
        all_results.extend(response["results"])
        
        # Stop if we've reached the last page
        if current_page >= response["total_pages"]:
            break
            
        current_page += 1
    
    return all_results

def update_page_size(config: ShipwellPaginationConfigV2, new_size: int) -> None:
    """
    Update the page size in pagination configuration
    
    Args:
        config: Pagination configuration
        new_size: New page size to use
    """
    if new_size < 1:
        raise ValueError("Page size must be greater than 0")
    config.page_size = new_size

def update_sort_order(config: ShipwellPaginationConfigV2, fields: List[str]) -> None:
    """
    Update the sort order in pagination configuration
    
    Args:
        config: Pagination configuration
        fields: List of fields to sort by (prepend '-' for descending)
    """
    config.ordering = fields

# Example usage
config = ShipwellPaginationConfigV2(
    status="tendered",
    page_size=50,
    ordering=["-created_at"]
)

headers = {
    "Accept-Type": "application/json",
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

# Get a specific page
page_data = get_shipments(headers, config, page=1)
print(f"Total pages: {page_data['total_pages']}")
print(f"Results count: {len(page_data['results'])}")

# Get all shipments
all_shipments = get_all_shipments(headers, config)
print(f"Total shipments: {len(all_shipments)}")

# Update page size
update_page_size(config, 100)

# Update sorting
update_sort_order(config, ["-pickup"])

# Get new first page with different ordering
page_data = get_shipments(headers, config, page=1)
print(f"Total pages: {page_data['total_pages']}")
print(f"Results count: {len(page_data['results'])}")

Example Usage

Here's how to use the pagination helper:

Initialize configuration:

Copy

Copied

config = ShipwellPaginationConfigV2(
status="tendered",
page_size=50,
ordering=["-created_at", "pickup"]
)

Get a specific page:

Copy

Copied

page_data = get_shipments(headers, config, page=1)

Get all pages:

Copy

Copied

all_shipments = get_all_shipments(headers, config)

Update page size:
Copy

Copied
```
update_page_size(config, 100)
```

Update sorting:

Copy

Copied

update_sort_order(config, ["-updated_at"])

Example get multiple shipments by mode request (advanced)

About This Request

This is an example of querying for shipments in any of the following modes of transportation: LTL (Less-Than Truck Load), FTL (Full Truck Load), PARCEL or RAIL .
This example purposefully shows a complex example of ORing together search criteria for mode as this same pattern would be used to query for OR searches for other array search properties on shipment like status , pickup_number , pro_number , tags , etc. See shipment list API reference for other properties or querystring parameters that may be utilized.
To see the full list of shipments mode see the shipment mode reference data documentation here .
You may also request code samples in other programming languages by utilizing Shipwell's AI-powered developer chatbot on the developer portal. Ask the chatbot to "Translate the following code sample into programming language X." where X is your desired programming language.

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/v2/shipments?page-size=10&mode=LTL&mode=FTL&mode=PARCEL&mode=RAIL' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const modeParamMultiValue = ["LTL", "FTL", "PARCEL", "RAIL"];
const basePath = "/v2";
const host = "sandbox-api.shipwell.com";

const urlSearchParams = new URLSearchParams({
  "page-size": 10, 
  // ... other parameters
});

modeParamMultiValue.forEach((x) => urlSearchParams.append("mode", x));
const query = urlSearchParams.toString(); // page-size=10&mode=LTL&mode=FTL&mode=PARCEL&mode=RAIL

const resp = await fetch(
  `https://${host}${basePath}/shipments?${query}`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

mode_param_value = "YOUR_mode_PARAMETER"
base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/shipments"

headers = {
    "Accept-Type": "application/json",
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

query_params = {
    "mode": mode_param_value,  # "mode": ["LTL", "FTL", "PARCEL", "RAIL"]
    "page-size": 10
}

response = requests.get(target_url, headers=headers, params=query_params)
data = response.json()
print(data)

Example get multiple shipments response

Copy

Copied

{
  "results": [
      {
        "id":"caaad729-4b6f-49bf-8f93-b9f3de73b6e8",
        "reference_id": "SK799X",
        // ...
      },
    // ... other shipments ...
  ],
  "page-size": 10,
  "total_pages": 100, // number of pages of items based on the page size
  "total_count": 1000 // number of total items that match the query (including the items outside the current page of items/results)
}

Handling Archived Shipments

By default, archived shipments are excluded from the results returned by the GET /v2/shipments shipment list endpoint. To customize the inclusion of archived and/or unarchived shipments, use the archived query parameter as follows:

Add the query/querystring parameter archived to true include only archived orders in the query results (i.e. ?archived=true ).
Add the query/querystring parameter archived to false include only unarchived orders in the query results ( i.e. ?archived=false ).
To include both archived and unarchived orders in the query results (i.e. all orders regardless of archived status) set the multi-value querystring archived parameter to both true and false by repeating the parameter with a different value in the querystring to OR the query (i.e. ?archived=true&archived=false ).

Create a Shipment

Shipments are created using the POST /v2/shipments/ shipment create endpoint.

Reference the quickstart shipment creation guide for details on how to create a shipment.

Update a Shipment

Shipments are updated using the PUT /v2/shipments/{shipment_id} shipment update endpoint.

Reference the quickstart shipment update guide for details on how to update a shipment.

Add or Upload Documents to a Shipment

Shipment documents are added or uploaded using the POST /v2/shipments/{shipment_id}/documents/ shipment document create API endpoint.

Reference the quickstart shipment document add or upload guide for details on how to add/create or upload a document to a shipment.