Managed Orders
Overview
Managed orders are loads created through the Managed Services module on the platform. They result from mutual agreements between shippers and providers that aim to simplify the load creation process.
In addition to requiring less input data, managed orders are not dispatched to a carrier, nor posted to the Load Board. Shippers only need to provide pickup and delivery locations as well as set a shipping date. Basic vehicle info such as year, make and model (or vin) is needed for each vehicle included in the load. Supported providers then generate different offers (quotes) based on the calculated inputs. Shippers can choose between options that vary in price, estimated transit time and method of delivery.
When a quote is selected, additional information may be required to book an order. This includes specific pickup and delivery details, vehicle data and customer (shipper) information. For the most part, providing these details is optional.
Keep in mind that if you opt for the automatic filling of contact information (assuming you have any saved contacts), future changes to the profile details of an existing customer and delivery/pickup details will not be reflected in a finished managed order or any successfully created load in general.
Once created, quotes are booked and become managed orders. They differ from standard orders by their assigned provider and generated internal order ID.
On this page, you can find descriptions, examples and sample request-response codes for primary managed order operations. Availability is limited to shippers and/or shipping companies.
Workflow
The following graph visualizes all stages a managed order needs to go through before it is created. Relevant APIs are indicated for each individual step.
- Create (Fetch) a Quote
- Select a Quote
- Create a Managed Order
To learn more about different enum values used across the page, check out Enum Values.
Create a Managed Order
Add a key
Before you can create a quote, add a Montway API key (if you would like to use Montway as a provider).
Link: PATCH https://ship.cars/api/quote-manager/v1/providers/montway/keys
Add a Montway key (Request)
{
"apiKey": "<key>"
}
The response will return the unique key of your provider.
Get keys
Link: GET https://staging.ship.cars/api/quote-manager/v1/providers/montway/keys
Request All Quotes
This API returns possible quotes for a potentially bookable managed order based on provided inputs (e.g. vehicle data, pickup date, delivery date). Only pickup and delivery zip codes are required.
On response, quotes are returned for every supported provider.
Link: POST https://ship.cars/api/quote-manager/v1/providers
Request
{
"pickupDate": "2022-08-26",
"trailerType": "OPEN",
"pickupStreet": "",
"pickupCity": "Schenectady",
"pickupState": "NY",
"pickupZipCode": "12306",
"deliveryStreet": "",
"deliveryCity": "West Chester Township",
"deliveryState": "OH",
"deliveryZipCode": "45069",
"vehicles": [
{
"vin": "KL4CJESB6EB523809",
"year": 2014,
"make": "Buick",
"model": "Encore",
"bodyType": "SUV",
"operableType": "OPERABLE"
},
{
"vin": "2G1WF52E759134136",
"year": 2005,
"make": "Chevrolet",
"model": "Impala",
"bodyType": "Car",
"operableType": "OPERABLE"
}
]
}
Response
{
"providers": [
{
"id": "YK41K",
"name": "montway",
"profilePictureUrl": "https://i.imgur.com/u1XoL3V.png"
}
],
"process_id": "KZ9EG"
}
You will need the process_id in order to proceed further.
All quotes can alternatively be received through an added webhook URL.
Get Provider Quotes
Through this API, you can get quotes only from a specific provider.
Link: GET https://ship.cars/api/quote-manager/v1/booking-details/YK41K
Response
{
"selectedQuoteId": "5EEEEEEEEEEEE33C",
"transitTime": "3-6 days",
"vehicles": [
{
"id": "YK41K",
"vin": "JF1ZNAA10D1702170",
"year": 2022,
"make": "BMW",
"model": "M5",
"bodyType": "SUV",
"operableType": "OPERABLE"
}
],
"pickupDate": "2022-03-23",
"pickupStreet": "161 W Cherry St",
"pickupCity": "Albion",
"pickupState": "IL",
"pickupZipCode": "62806",
"deliveryStreet": "161 W Cherry St",
"deliveryCity": "Albion",
"deliveryState": "IL",
"deliveryZipCode": "62806",
"trailerType": "OPEN",
"selectedProviderId": "YK41K",
"selectedProviderName": "MartinTLC",
"selectedProviderProfilePictureUrl": "https://www.image.com/provider.jpg",
"service": "7 days pick up",
"priceInCents": 1000,
"chosenIdentity": "7",
"chosenRateType": "regular",
"quotes": [
{
"payload": {
"quoteId": "CE13C6919F02CE15",
"quoteRefId": "656316",
"expiresAt": "2023-10-17T03:05:51-05:00",
"transitTime": {
"min": 1.0,
"max": 4.0,
"shortLabel": "1 - 4 days",
"label": "Transit time: 1 - 4 days"
},
"vehicle": [
{
"id": null,
"vin": null,
"year": 2013,
"make": "Scion",
"model": "FR-S",
"bodyType": null,
"operableType": "OPERABLE"
},
{
"id": null,
"vin": null,
"year": 2022,
"make": "BMW",
"model": "M5",
"bodyType": null,
"operableType": "OPERABLE"
}
],
"rates": [
{
"identity": "7",
"pickupWindow": 7,
"payment": "regular",
"price": "899.00",
"label": "7 days pick up",
"subcharges": null
},
{
"identity": "2",
"pickupWindow": 1,
"payment": "regular",
"price": "929.00",
"label": "1 day pick up",
"subcharges": null
}
]
},
"providerId": "YK41K",
"providerName": "MartinTLC",
"providerProfilePictureUrl": "https://www.image.com/provider.jpg"
}
]
}
Make a Quote selection
This API confirms and books a selection of a quote offered by a provider. Use the process_id from the Request All Quotes API to make the selection, and then proceed to book the order.
Link: POST https://ship.cars/api/quote-manager/v1/booking-details
The payload should be:
Request
{
"providerId": "YK41K",
"quoteId": "5EEEEEEEEEEEE33C",
"rateType": "regular",
"rateIdentity": "7",
"service": "7 days pick up",
"processId": "YK41K",
"priceInCents": 1000,
"transitTime": "3-6 days"
}
When you have this mapping from a provider quote, you can observe its rate. Different rates represent basic parameters of the selected quote, such as its price, pickup window and transit time.
"transitTime": {
"min": 1.0,
"max": 4.0,
"shortLabel": "1 - 4 days",
"label": "Transit time: 1 - 4 days"
},
...
"rates": [
{
"identity": "2",
"pickupWindow": 1,
"payment": "regular",
"price": "929.00",
"label": "1 day pick up",
"subcharges": null
},
...
]
Mapping:
"quoteId" -> "payload.quoteId"
"rateType" -> "payload.rates[0].payment"
"rateIdentity" -> "payload.rates[0].identity"
"service" -> "payload.rates[0].label"
"priceInCents" -> "payload.rates[0].price" - converted to cents
"transitTime" -> "payload.transitTime.label"
Create an Order
The final step is to create your managed order. A quote must already be selected and booked.
Pickup and delivery phone number, first and last name, and street address are required.
The response order_id field is used in the validation of the vehicle gatepass document.
Link: POST https://ship.cars/api/quote-manager/v1/orders
Request
{
"providerId": "YK41K",
"orderId": "CUSTOM_ID_2",
"quoteId": "5EEEEEEEEEEEE33C",
"rateType": "regular",
"rateIdentity": "7",
"pickupDate": "2022-03-23",
"processId": "YK41K",
"transitTime": "3-6 days",
"customer": {
"id": "YK41K",
"firstName": "Martin",
"lastName": "Smith",
"phoneNumber": "3033210789",
"companyName": "MartinTLC",
"emailAddress": "[email protected]"
},
"pickup": {
"id": "YK41K",
"firstName": "Martin",
"lastName": "Smith",
"phoneNumber": "3033210789",
"companyName": "MartinTLC",
"mobileNumber": "3033210789",
"workNumber": "3033210789",
"streetAddress": "string",
"locationId": "XC223"
},
"delivery": {
"id": "YK41K",
"firstName": "Martin",
"lastName": "Smith",
"phoneNumber": "3033210789",
"companyName": "MartinTLC",
"mobileNumber": "3033210789",
"workNumber": "3033210789",
"streetAddress": "string",
"locationId": "XC223"
},
"gatepasses": [
{
"attachmentId": "YK41K",
"vehicleId": "YK41K",
"lotNumber": "CS123",
"stockNumber": "XC#42",
"buyerNumber": "123X2XD"
}
],
"customerComment": "Be careful with the car"
}
Response
<ORDER_ID>
Get Load
This API uses the order_id field to fetch response data about an existing managed order. The response schema matches what is typically returned for all standard loads, the only difference being that the orderInformation object will be filled.
Link: GET https://ship.cars/api/shipperlite/posting/v2/integrators/loads/K9RV0
Response
{
"id": "YK41K",
"status": "POSTED",
"shipperLoadId": "CS1234X",
"externalId": "123XX",
"load": {
"id": "YK41K",
"dispatchInstructions": "Please, do not come before 6.",
"useEnclosedTrailer": true,
"useM22InspectionGuide": true,
"useGpsTracking": true
},
"route": {
"id": "YK41K",
"pickupDateDetail": {
"id": "YK41K",
"estimatedEndDate": "2022-03-23",
"estimatedStartDate": "2022-03-21",
"restriction": "NO_RESTRICTIONS"
},
"deliveryDateDetail": {
"id": "YK41K",
"estimatedEndDate": "2022-03-23",
"estimatedStartDate": "2022-03-21",
"restriction": "NO_RESTRICTIONS"
},
"deliveryLocation": {
"id": "YK41K",
"city": "Albion",
"state": "IL",
"street": "161 W Cherry St",
"zipCode": "62806",
"locationId": "XC223",
"longitude": "-94.2332754",
"latitude": "39.3514073"
},
"pickupLocation": {
"id": "YK41K",
"city": "Albion",
"state": "IL",
"street": "161 W Cherry St",
"zipCode": "62806",
"locationId": "XC223",
"longitude": "-94.2332754",
"latitude": "39.3514073"
},
"distanceInMiles": 1345.56,
"transitTime": "5-6 days"
},
"shippingItems": [
{
"id": "YK41K",
"vehicle": {
"bodyType": "Car",
"buyerNumber": "123CXS23",
"color": "red",
"lotNumber": "123CXS23",
"stockNumber": "123CXS23",
"make": "BMW",
"model": "218i",
"vin": "1D4GP24R85B225747",
"year": 2022,
"id": "YK41K",
"length": "4526",
"height": "1420",
"width": "1800",
"weight": "1325",
"logo": "https://image.com/bmw.jpg",
"operableType": "OPERABLE",
"lbExternalId": "123CXS23"
},
"attachments": [
{
"fileUrl": "https://www.media.com/attachment1.jpg",
"shareWith": "CARRIER",
"id": "YK41K",
"lbExternalId": "CS1235XX",
"loadLegId": "YK41K",
"shippingItemId": "YK41K",
"creatorType": "SHIPPER",
"originalFileName": "Dispatch Sheet"
}
]
}
],
"payments": [
{
"id": "YK41K",
"carrierPayInCents": 10000,
"notes": "I prefer cards.",
"paymentType": "COD",
"paymentTransactionType": "CUSTOMER_TO_CARRIER",
"paymentMethod": "CASH",
"paymentTermsBeginType": null,
"paymentTermsType": null
}
],
"carrierPayInCents": 100000,
"orderInformation": {
"id": "YK41K",
"refId": "1234567XX",
"orderId": "1234567XX",
"selectedQuoteId": "5EEEEEEEEEEEE33C",
"selectedQuoteRateType": "regular",
"providerId": "YK41K",
"providerName": "MartinTLC",
"providerLogoUrl": "https://www.image.com/provider.jpg"
},
"contract": {
"id": "YK41K",
"shipper": {
"id": "YK41K",
"companyName": "MartinTLC",
"email": "[email protected]",
"name": "Martin",
"primaryPhone": "1234567890",
"primaryPhoneNotes": "Do not call me before 8",
"secondaryPhone": "1234567890",
"secondaryPhoneNotes": "Do not call me before 8",
"thirdPhone": "1234567890",
"thirdPhoneNotes": "Do not call me before 8",
"workingHours": "From 5 to 12",
"location": {
"id": "YK41K",
"city": "Albion",
"state": "IL",
"street": "161 W Cherry St",
"zipCode": "62806",
"locationId": "XC223"
},
"type": "CUSTOMER",
"notes": "string"
}
},
"attachments": [
{
"fileUrl": "https://www.media.com/attachment1.jpg",
"shareWith": "CARRIER",
"id": "YK41K",
"lbExternalId": "CS1235XX",
"loadLegId": "YK41K",
"shippingItemId": "YK41K",
"creatorType": "SHIPPER",
"originalFileName": "Dispatch Sheet"
}
],
"carrierOffers": [
{
"id": "YK41K",
"priceInCents": 100000,
"carrierDot": "1111111",
"negotiationId": "123X",
"status": "active",
"externalId": "123X",
"companyId": "123X",
"expirationDate": "2022-08-23T09:35:07.237Z"
}
],
"pickupContact": {
"id": "YK41K",
"companyName": "MartinTLC",
"email": "[email protected]",
"name": "Martin",
"primaryPhone": "1234567890",
"primaryPhoneNotes": "Do not call me before 8",
"secondaryPhone": "1234567890",
"secondaryPhoneNotes": "Do not call me before 8",
"thirdPhone": "1234567890",
"thirdPhoneNotes": "Do not call me before 8",
"workingHours": "From 5 to 12",
"location": {
"id": "YK41K",
"city": "Albion",
"state": "IL",
"street": "161 W Cherry St",
"zipCode": "62806",
"locationId": "XC223"
},
"type": "CUSTOMER",
"notes": "string"
},
"extRateCalculationId": "YKXS23IJ",
"carrier": {
"id": "YK41K",
"email": "[email protected]",
"name": "Martin",
"primaryPhone": "1234567890",
"primaryPhoneNotes": "Do not call me before 8",
"secondaryPhone": "1234567890",
"secondaryPhoneNotes": "Do not call me before 8",
"thirdPhone": "1234567890",
"thirdPhoneNotes": "Do not call me before 8",
"logo": "https://www.image.com/logo.jpg",
"usDot": 1234567,
"lbExternalId": "123X",
"location": {
"id": "YK41K",
"city": "Albion",
"state": "IL",
"street": "161 W Cherry St",
"zipCode": "62806",
"locationId": "XC223"
},
"userManagementId": "123X"
},
"driver": {
"id": "YK41K",
"name": "Martin",
"email": "[email protected]",
"phone": "1234567890",
"additionalPhone": "1234567890",
"lbExternalId": "123X",
"profilePictureUrl": "https://www.image.com/picture.jpg",
"userManagementId": "123X"
},
"pickupSignatureRequired": false,
"deliverySignatureRequired": false,
"deliveryContact": {
"id": "YK41K",
"companyName": "MartinTLC",
"email": "[email protected]",
"name": "Martin",
"primaryPhone": "1234567890",
"primaryPhoneNotes": "Do not call me before 8",
"secondaryPhone": "1234567890",
"secondaryPhoneNotes": "Do not call me before 8",
"thirdPhone": "1234567890",
"thirdPhoneNotes": "Do not call me before 8",
"workingHours": "From 5 to 12",
"location": {
"id": "YK41K",
"city": "Albion",
"state": "IL",
"street": "161 W Cherry St",
"zipCode": "62806",
"locationId": "XC223"
},
"type": "CUSTOMER",
"notes": "string"
},
"publicLinkInfo": {
"id": "YK41K",
"publicLinkKey": "1231435435",
"publicLink": "https://www.public-link.com"
}
}
Update Load
Using retrieved information from the Get Load endpoint, this API allows you to make changes to a specific managed order - in other words, updating one or more of its fields.
Keep in mind that you cannot update a managed order if its status is one of the following:
DELIVERED - the load is delivered and cannot be changed
ARCHIVED - the load is archived
The response body is the same as the one you receive on create.
Link: PUT https://ship.cars/api/shipperlite/posting/v2/integrators/managed-orders/K9RV0
Get Location Data for a Load
This API returns the location tracking data of a specific managed order using the externalId field from its create response. To use location history, enable location sharing for the order, which should also be approved by its dispatcher.
You can obtain a valid externalId once the load status becomes DISPATCHED.
Link: GET https://ship.cars/api/location_tracking/history/vg9q38/
Location Data Response
[
{
"status": "ongoing",
"timestamp": "2021-07-22T09:41:20.483000+00:00",
"location": {
"longitude": -119.8524937,
"latitude": 37.5945638
}
},
{
"status": "ongoing",
"timestamp": "2021-07-22T10:15:20.483000+00:00",
"location": {
"longitude": -119.2053407,
"latitude": 38.1888124
}
},
{
"status": "ongoing",
"timestamp": "2021-07-22T10:42:20.483000+00:00",
"location": {
"longitude": -119.4643684,
"latitude": 38.5128509
}
},
{
"status": "ongoing",
"timestamp": "2021-07-22T11:02:20.483000+00:00",
"location": {
"longitude": -117.7764446,
"latitude": 38.0186303
}
},
{
"status": "ongoing",
"timestamp": "2021-07-23T11:02:20.483000+00:00",
"location": {
"longitude": -119.1196436,
"latitude": 37.9571971
}
},
{
"status": "ongoing",
"timestamp": "2021-09-24T07:41:20.483000+00:00",
"location": {
"longitude": -118.8517224,
"latitude": 37.5945638
}
}
]
Get the BOL & Images for a Load
This API uses the Get Load response to retrieve a PDF file containing the load’s bill of lading document. Inside, you’ll be able to access a link leading to the BOL’s attachments (images), if applicable.
There can be attachments per managed order and per specific shipping item such as vehicle.
Each attachment contains a public link with secure URL (check the fileURL from the Json below).
Sample response of attachments on shipping item level:
Shipping Items Attachments
"shippingItems": [
{
"id": "8J5LV",
"vehicle": {
"bodyType": "Car",
"buyerNumber": null,
"color": null,
"lotNumber": null,
"stockNumber": null,
"make": "Acura",
"model": "Legend",
"vin": "JH4KA4540JC050162",
"year": 1988,
"id": "8J5LV",
"length": "190.00",
"height": "52.00",
"width": "68.0",
"weight": "3239",
"logo": "https://storage.googleapis.com/ship-cars-make-logos/acura-logo.png",
"operableType": "OPERABLE",
"lbExternalId": null
},
"attachments": [
{
"fileUrl": "https://media.ship.cars/media/postings/attachments/d93a1ac3-9817-4f96-a6eb-37c6bd6cae38.jpg",
"shareWith": null,
"id": "XWP21",
"lbExternalId": null,
"loadLegId": null,
"shippingItemId": "8J5LV",
"creatorType": "SHIPPER",
"originalFileName": "4mb_image.jpg"
}
]
}
],
Updated over 2 years ago