Create a new Shipment

Shipments start in a "draft" state by default. Only the metadata parameter set to "open": false, "archived": false, and tags: set to [] are required to begin a draft shipment.

SecurityAuthToken
Request
header Parameters
X-Company-Id
string

allows request to retrieve information about the company given in the header instead of the company associated with the requesting user

Request Body schema: application/json
required
Array of objects (Accessorial)
additional_bol_recipients
Array of strings

Additional email address to send the BOL to upon booking

object (AuctionStats)
bol_number
string or null
cancellation_reason
string or null
capacity_provider_customer_reference_number
string or null

Customer reference number that came back from the capacity provider

created_at
string or null <date-time>
created_by_source
string or null (CreatedBySourceTypeEnum)

This nullable property indicates the source of how the shipment was created. This field is readonly and cannot be set via API. SHIPWELL_WEB indicates that the shipment was created from the web-based frontend; IMPORT is from the shipment importer/uploader; TENDER created from inbound EDI tender; SHIPWELL_WEB_UNAUTH is from supplier invites; OTHER is from everything else including API created.

Enum: "SHIPWELL_WEB" "IMPORT" "TENDER" "SHIPWELL_WEB_UNAUTH" "OTHER"
object (SlimUser)
object (CurrentShipmentAddress)
object (ShipmentCustomData)

Custom data for Shipment

object (SlimCompany)
customer_reference_number
string or null
delayed
boolean
description
string or null
documents_count
integer or null
drayage_booking_number
string or null
drayage_carrier_scac_code
string or null
drayage_chassis_number
string or null
drayage_container_number
string or null
drayage_container_return_date
string or null
drayage_estimated_arrival_date
string or null
drayage_house_bol_number
string or null
drayage_last_free_date
string or null
drayage_release_date
string or null
drayage_seal_number
string or null
object (SlimEquipmentConfig)
object (EquipmentType)

Equipment type

est_trip_miles
number or null <float>
external_tracking_link
string or null
final_trip_miles
number or null <float>
group_id
string or null
id
required
string <uuid>
is_watchable
boolean
is_watched
boolean
last_cloned_at
string or null <date-time>
Array of objects (ShipmentLineItem)
marked_as_paid_by_user
string or null <uuid>
markup
number or null <float>
messages_count
integer or null
object (ShipmentMetadata)

Contextual metadata about a shipment

object (ShipmentMode)

Standardized code for a shipment mode

movement_type
string or null (ShipmentMovementType)
Enum Value Description
DOOR_TO_DOOR

Door To Door

DOOR_TO_PORT

Door To Port

PORT_TO_DOOR

Port To Door

PORT_TO_PORT

Port to Port

name
string or null
next_planned_stop_id
string or null <uuid>
notes_count
integer or null
notes_for_carrier
string or null
parcel_pickup_status
string or null
Enum: "CANCELLED" "DELAYED" "DELIVERED" "IN_TRANSIT" "NOT_SCHEDULED" "SCHEDULED"
pickup_number
string or null
preferred_currency
string or null
Enum: "CAD" "CNY" "EUR" "MXN" "USD"
pro_number
string or null
purchase_order_number
string or null
rail_car_number
string or null
rail_car_status
string or null
Enum: "ARRIVAL_TRANSIT_LOCATION" "BAD_ORDER" "ARRIVAL_AT_DESTINATION" "MOTOR_CARRIER_DEPARTURE" "FLATCAR_BAD_ORDER" "BAD_ORDER_RELEASE" "EQUIPMENT_DELAYED_OR_HELD" "EQUIPMENT_OFFERED_IN_INTERCHANGE" "INTERCHANGE_DELIVERY" "INTERMODAL_INTERCHANGE" "MOTOR_CARRIER_ARRIVAL" "MOTOR_CARRIER_MOVE" "NO_BILL" "DEPARTURE" "FLATCAR_BAD_ORDER_RELEASE" "INTERCHANGE_RECEIVED" "STORAGE" "RAMPED" "DE_RAMPED" "RELEASED" "PULL" "CONSTRUCTIVE_PLACEMENT_NOTIFY" "ACTUAL_PLACEMENT" "ETA" "LADING_TRANSFER_TO" "LADING_TRANSFER_FROM" "RELEASE_FROM_HOLD_OR_MISCELLANEOUS"
reference_id
string or null
Array of objects (ShipmentReference)
Default: []
object (CarrierAssignment)
object (CarrierStatusCarrierAssignment)
Array of objects (ShipmentRep)

Representatives for the Shipment from within the requesting user's own company

Array of objects (SlimRFQ)

All RFQs this Shipment has run, slimmed down to exclude their quotes

object (ServiceLevel)

Standardized code for a shipment service level

shipment_pickup
string or null <uuid>
significantly_modified_at
string or null <date-time>

Not implemented

state
string (ShipmentStates)
Enum Value Description
appointment_pending

appointment_pending

arrived_at_rail_facility

arrived_at_rail_facility

at_delivery

at_delivery

at_destination_airport

at_destination_airport

at_destination_port

at_destination_port

at_origin_airport

at_origin_airport

at_origin_port

at_origin_port

at_pickup

at_pickup

available

available

available_at_rail_facility

available_at_rail_facility

cancelled

cancelled

carrier_confirmed

carrier_confirmed

cleared_customs

cleared_customs

customs_hold

customs_hold

customs_review

customs_review

delivered

delivered

departed_on_rail

departed_on_rail

discharged

discharged

dispatched

dispatched

draft

draft

empty_outgated

empty_outgated

empty_returned

empty_returned

exception

exception

full_ingated

full_ingated

full_outgated

full_outgated

full_outgated_from_rail_facility

full_outgated_from_rail_facility

in_transit

in_transit

loaded

loaded

loaded_on_rail

loaded_on_rail

quote_accepted

quote_accepted

quoting

quoting

reconciled

reconciled

tendered

tendered

vessel_arrived

vessel_arrived

vessel_departed

vessel_departed

Array of objects (StopDetail)
temperature_lower_limit
number or null <float>
temperature_unit
string or null
Enum: "F" "C"
temperature_upper_limit
number or null <float>
Array of objects (ShipmentTimelineEvent)
timeline_last_updated_at
string or null <date-time>
total_declared_value
number or null <float>
total_declared_value_currency
string or null
Enum: "CAD" "CNY" "EUR" "MXN" "USD"
total_linear_feet
integer or null <int32>
total_miles
number or null <float>
total_quantity_override
integer or null <int32>
object (TotalWeightOverride)
tracking_number
string or null
trailer_name
string or null
updated_at
string or null <date-time>
v3_shipment_id
string or null
version
integer or null
Enum: 2 3
object (CapacityProviderOptions)
carrier_reference_code
string or null
object (Company)
Array of objects or null (DispatchJob)
object (FedexShipmentOptions)

Shipment rating and dispatch options specific to FedEx

object (Quote)
most_recently_awarded_quote_id
string or null <uuid>
object (TenderGet)
most_recently_awarded_tender_id
string or null <uuid>
time_to_pickup
string or null
object (UPSShipmentOptions)

Shipment rating and dispatch options specific to UPS

object (USPSShipmentOptions)

Shipment rating and dispatch options specific to USPS

Responses
201

Successfully created a Shipment

Response Schema: application/json
Array of objects (Accessorial)
additional_bol_recipients
Array of strings

Additional email address to send the BOL to upon booking

object (AuctionStats)
bol_number
string or null
cancellation_reason
string or null
capacity_provider_customer_reference_number
string or null

Customer reference number that came back from the capacity provider

created_at
string or null <date-time>
created_by_source
string or null (CreatedBySourceTypeEnum)

This nullable property indicates the source of how the shipment was created. This field is readonly and cannot be set via API. SHIPWELL_WEB indicates that the shipment was created from the web-based frontend; IMPORT is from the shipment importer/uploader; TENDER created from inbound EDI tender; SHIPWELL_WEB_UNAUTH is from supplier invites; OTHER is from everything else including API created.

Enum: "SHIPWELL_WEB" "IMPORT" "TENDER" "SHIPWELL_WEB_UNAUTH" "OTHER"
object (SlimUser)
object (CurrentShipmentAddress)
object (ShipmentCustomData)

Custom data for Shipment

object (SlimCompany)
customer_reference_number
string or null
delayed
boolean
description
string or null
documents_count
integer or null
drayage_booking_number
string or null
drayage_carrier_scac_code
string or null
drayage_chassis_number
string or null
drayage_container_number
string or null
drayage_container_return_date
string or null
drayage_estimated_arrival_date
string or null
drayage_house_bol_number
string or null
drayage_last_free_date
string or null
drayage_release_date
string or null
drayage_seal_number
string or null
object (SlimEquipmentConfig)
object (EquipmentType)

Equipment type

est_trip_miles
number or null <float>
external_tracking_link
string or null
final_trip_miles
number or null <float>
group_id
string or null
id
required
string <uuid>
is_watchable
boolean
is_watched
boolean
last_cloned_at
string or null <date-time>
Array of objects (ShipmentLineItem)
marked_as_paid_by_user
string or null <uuid>
markup
number or null <float>
messages_count
integer or null
object (ShipmentMetadata)

Contextual metadata about a shipment

object (ShipmentMode)

Standardized code for a shipment mode

movement_type
string or null (ShipmentMovementType)
Enum Value Description
DOOR_TO_DOOR

Door To Door

DOOR_TO_PORT

Door To Port

PORT_TO_DOOR

Port To Door

PORT_TO_PORT

Port to Port

name
string or null
next_planned_stop_id
string or null <uuid>
notes_count
integer or null
notes_for_carrier
string or null
parcel_pickup_status
string or null
Enum: "CANCELLED" "DELAYED" "DELIVERED" "IN_TRANSIT" "NOT_SCHEDULED" "SCHEDULED"
pickup_number
string or null
preferred_currency
string or null
Enum: "CAD" "CNY" "EUR" "MXN" "USD"
pro_number
string or null
purchase_order_number
string or null
rail_car_number
string or null
rail_car_status
string or null
Enum: "ARRIVAL_TRANSIT_LOCATION" "BAD_ORDER" "ARRIVAL_AT_DESTINATION" "MOTOR_CARRIER_DEPARTURE" "FLATCAR_BAD_ORDER" "BAD_ORDER_RELEASE" "EQUIPMENT_DELAYED_OR_HELD" "EQUIPMENT_OFFERED_IN_INTERCHANGE" "INTERCHANGE_DELIVERY" "INTERMODAL_INTERCHANGE" "MOTOR_CARRIER_ARRIVAL" "MOTOR_CARRIER_MOVE" "NO_BILL" "DEPARTURE" "FLATCAR_BAD_ORDER_RELEASE" "INTERCHANGE_RECEIVED" "STORAGE" "RAMPED" "DE_RAMPED" "RELEASED" "PULL" "CONSTRUCTIVE_PLACEMENT_NOTIFY" "ACTUAL_PLACEMENT" "ETA" "LADING_TRANSFER_TO" "LADING_TRANSFER_FROM" "RELEASE_FROM_HOLD_OR_MISCELLANEOUS"
reference_id
string or null
Array of objects (ShipmentReference)
Default: []
object (CarrierAssignment)
object (CarrierStatusCarrierAssignment)
Array of objects (ShipmentRep)

Representatives for the Shipment from within the requesting user's own company

Array of objects (SlimRFQ)

All RFQs this Shipment has run, slimmed down to exclude their quotes

object (ServiceLevel)

Standardized code for a shipment service level

shipment_pickup
string or null <uuid>
significantly_modified_at
string or null <date-time>

Not implemented

state
string (ShipmentStates)
Enum Value Description
appointment_pending

appointment_pending

arrived_at_rail_facility

arrived_at_rail_facility

at_delivery

at_delivery

at_destination_airport

at_destination_airport

at_destination_port

at_destination_port

at_origin_airport

at_origin_airport

at_origin_port

at_origin_port

at_pickup

at_pickup

available

available

available_at_rail_facility

available_at_rail_facility

cancelled

cancelled

carrier_confirmed

carrier_confirmed

cleared_customs

cleared_customs

customs_hold

customs_hold

customs_review

customs_review

delivered

delivered

departed_on_rail

departed_on_rail

discharged

discharged

dispatched

dispatched

draft

draft

empty_outgated

empty_outgated

empty_returned

empty_returned

exception

exception

full_ingated

full_ingated

full_outgated

full_outgated

full_outgated_from_rail_facility

full_outgated_from_rail_facility

in_transit

in_transit

loaded

loaded

loaded_on_rail

loaded_on_rail

quote_accepted

quote_accepted

quoting

quoting

reconciled

reconciled

tendered

tendered

vessel_arrived

vessel_arrived

vessel_departed

vessel_departed

Array of objects (StopDetail)
temperature_lower_limit
number or null <float>
temperature_unit
string or null
Enum: "F" "C"
temperature_upper_limit
number or null <float>
Array of objects (ShipmentTimelineEvent)
timeline_last_updated_at
string or null <date-time>
total_declared_value
number or null <float>
total_declared_value_currency
string or null
Enum: "CAD" "CNY" "EUR" "MXN" "USD"
total_linear_feet
integer or null <int32>
total_miles
number or null <float>
total_quantity_override
integer or null <int32>
object (TotalWeightOverride)
tracking_number
string or null
trailer_name
string or null
updated_at
string or null <date-time>
v3_shipment_id
string or null
version
integer or null
Enum: 2 3
object (CapacityProviderOptions)
carrier_reference_code
string or null
object (Company)
Array of objects or null (DispatchJob)
object (FedexShipmentOptions)

Shipment rating and dispatch options specific to FedEx

object (Quote)
most_recently_awarded_quote_id
string or null <uuid>
object (TenderGet)
most_recently_awarded_tender_id
string or null <uuid>
Array of objects or null (RelatedOrder)
time_to_pickup
string or null
object (UPSShipmentOptions)

Shipment rating and dispatch options specific to UPS

object (USPSShipmentOptions)

Shipment rating and dispatch options specific to USPS

default

Default error response

post/shipments/
Request samples
application/json
{
  • "accessorials": [
    ],
  • "additional_bol_recipients": [
    ],
  • "auction_stats": {
    },
  • "bol_number": "string",
  • "cancellation_reason": "string",
  • "capacity_provider_customer_reference_number": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_source": "SHIPWELL_WEB",
  • "created_by_user": {
    },
  • "current_address": {
    },
  • "custom_data": {
    },
  • "customer": {
    },
  • "customer_reference_number": "string",
  • "delayed": true,
  • "description": "string",
  • "documents_count": 0,
  • "drayage_booking_number": "string",
  • "drayage_carrier_scac_code": "string",
  • "drayage_chassis_number": "string",
  • "drayage_container_number": "string",
  • "drayage_container_return_date": "string",
  • "drayage_estimated_arrival_date": "string",
  • "drayage_house_bol_number": "string",
  • "drayage_last_free_date": "string",
  • "drayage_release_date": "string",
  • "drayage_seal_number": "string",
  • "equipment_config": {
    },
  • "equipment_type": {
    },
  • "est_trip_miles": 0.1,
  • "external_tracking_link": "string",
  • "final_trip_miles": 0.1,
  • "group_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_watchable": true,
  • "is_watched": true,
  • "last_cloned_at": "2019-08-24T14:15:22Z",
  • "line_items": [
    ],
  • "marked_as_paid_by_user": "11a0a5f3-c5cd-4ba2-a712-5f479124aeb4",
  • "markup": 0.1,
  • "messages_count": 0,
  • "metadata": {
    },
  • "mode": {
    },
  • "movement_type": "string",
  • "name": "string",
  • "next_planned_stop_id": "822d3372-10ca-4acf-91c2-017f6e0f1f1e",
  • "notes_count": 0,
  • "notes_for_carrier": "string",
  • "parcel_pickup_status": "CANCELLED",
  • "pickup_number": "string",
  • "preferred_currency": "CAD",
  • "pro_number": "string",
  • "purchase_order_number": "string",
  • "rail_car_number": "string",
  • "rail_car_status": "ARRIVAL_TRANSIT_LOCATION",
  • "reference_id": "string",
  • "references": [ ],
  • "relationship_to_customer": {
    },
  • "relationship_to_vendor": {
    },
  • "reps": [
    ],
  • "rfqs": [
    ],
  • "service_level": {
    },
  • "shipment_pickup": "ee3aacbb-db54-4cb4-b6ae-7fb1f7074d15",
  • "significantly_modified_at": "2019-08-24T14:15:22Z",
  • "state": "string",
  • "stops": [
    ],
  • "temperature_lower_limit": 0.1,
  • "temperature_unit": "F",
  • "temperature_upper_limit": 0.1,
  • "timeline_events": [
    ],
  • "timeline_last_updated_at": "2019-08-24T14:15:22Z",
  • "total_declared_value": 0.1,
  • "total_declared_value_currency": "CAD",
  • "total_linear_feet": 0,
  • "total_miles": 0.1,
  • "total_quantity_override": 0,
  • "total_weight_override": {
    },
  • "tracking_number": "string",
  • "trailer_name": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "v3_shipment_id": "string",
  • "version": 2,
  • "capacity_provider_options": {
    },
  • "carrier_reference_code": "string",
  • "current_carrier": {
    },
  • "dispatch_jobs": [
    ],
  • "fedex_specific_options": {
    },
  • "most_recently_awarded_quote": {
    },
  • "most_recently_awarded_quote_id": "8d624590-e9d2-4f29-aa23-67aafde3f45e",
  • "most_recently_awarded_tender": {
    },
  • "most_recently_awarded_tender_id": "bbf23af1-7594-45e8-9f7f-d0481f4e6ccb",
  • "time_to_pickup": "string",
  • "ups_specific_options": {
    },
  • "usps_specific_options": {
    }
}
Response samples
application/json
{
  • "accessorials": [
    ],
  • "additional_bol_recipients": [
    ],
  • "auction_stats": {
    },
  • "bol_number": "string",
  • "cancellation_reason": "string",
  • "capacity_provider_customer_reference_number": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_source": "SHIPWELL_WEB",
  • "created_by_user": {
    },
  • "current_address": {
    },
  • "custom_data": {
    },
  • "customer": {
    },
  • "customer_reference_number": "string",
  • "delayed": true,
  • "description": "string",
  • "documents_count": 0,
  • "drayage_booking_number": "string",
  • "drayage_carrier_scac_code": "string",
  • "drayage_chassis_number": "string",
  • "drayage_container_number": "string",
  • "drayage_container_return_date": "string",
  • "drayage_estimated_arrival_date": "string",
  • "drayage_house_bol_number": "string",
  • "drayage_last_free_date": "string",
  • "drayage_release_date": "string",
  • "drayage_seal_number": "string",
  • "equipment_config": {
    },
  • "equipment_type": {
    },
  • "est_trip_miles": 0.1,
  • "external_tracking_link": "string",
  • "final_trip_miles": 0.1,
  • "group_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_watchable": true,
  • "is_watched": true,
  • "last_cloned_at": "2019-08-24T14:15:22Z",
  • "line_items": [
    ],
  • "marked_as_paid_by_user": "11a0a5f3-c5cd-4ba2-a712-5f479124aeb4",
  • "markup": 0.1,
  • "messages_count": 0,
  • "metadata": {
    },
  • "mode": {
    },
  • "movement_type": "string",
  • "name": "string",
  • "next_planned_stop_id": "822d3372-10ca-4acf-91c2-017f6e0f1f1e",
  • "notes_count": 0,
  • "notes_for_carrier": "string",
  • "parcel_pickup_status": "CANCELLED",
  • "pickup_number": "string",
  • "preferred_currency": "CAD",
  • "pro_number": "string",
  • "purchase_order_number": "string",
  • "rail_car_number": "string",
  • "rail_car_status": "ARRIVAL_TRANSIT_LOCATION",
  • "reference_id": "string",
  • "references": [ ],
  • "relationship_to_customer": {