Create a Shipment or Request a Booking

Create a Multi-modal shipment with or without an Ocean booking request or create just an Ocean booking request to send to carriers.

Create a Multi-modal shipment without an Ocean booking request.

Requirements

At a minimum, have the following information

Shipment Identifier
Shipment Information/Data
- Pickup and delivery stop information for this shipment including
  - Stop ID
  - Stop Type (PICKUP and DELIVERY)
  - Company Name of the Stop Contact
  - Stop Location Address or Geocoordinates
  - Route Segment fromStopId and toStopId

Workflow

Complete these steps:

Please, connect with your project44 Technical Contact for the Booking API Reference Documentation.
Prepare a POST request to /services/booking/v1/shipments. For example,

JSON

{
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "SHIPMENT-12345"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        "id": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
        "type": "PICKUP",
        "arrivalDate": "2092-12-10",
        "location": {
          "address": {
            "addressLines": [
              "222 W. Merchandise Mart Plaza",
              "Suite 1744"
            ],
            "postalCode": "60654",
            "city": "Chicago",
            "state": "IL",
            "country": "US"
          }
        }
      },
      {
        "id": "195e34be-d7be-4b8d-ab1a-de18babe3e40",
        "type": "DELIVERY",
        "arrivalDate": "2092-12-12",
        "location": {
          "address": {
            "addressLines": [
              "3800 N Lamar Blvd",
              "Suite 210"
            ],
            "postalCode": "78756",
            "city": "Austin",
            "state": "TX",
            "country": "US"
          }
        }
      }
    ],
    "routeSegments": [
      {
        "id": "2063ccce-a97f-4409-b92a-48659880157d",
        "fromStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
        "toStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e"
      }
    ]
  },
  "attributes": [
    {
      "name": "attribute name",
      "values": [
        "string value 1",
        "string value 2"
      ]
    }
  ]
}

This an example of a potential request. For the full request schema and descriptions for all fields and objects, please, connect with your project44 Technical Contact to receive the Booking API Reference Documentation.

Send the request.

Expected System Responses

The request is successfully submitted and confirmed when a 200 response is received.

JSON

{
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "SHIPMENT-12345"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        "id": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a",
        "type": "PICKUP",
        "arrivalDate": "2092-12-10",
        "arrivalAppointmentWindow": {
          "startTime": "10:15:00",
          "endTime": "12:45:00"
        },
        "contacts": [],
        "accessorials": [],
        "location": {
          "identifiers": [],
          "address": {
            "addressLines": [
              "222 W. Merchandise Mart Plaza",
              "Suite 1744"
            ],
            "postalCode": "60654",
            "city": "Chicago",
            "state": "IL",
            "country": "US"
          }
        }
      },
      {
        "id": "d0d8c4cd-681b-4707-9f38-631463ab60ad",
        "type": "DELIVERY",
        "arrivalDate": "2092-12-12",
        "arrivalAppointmentWindow": {
          "startTime": "15:15:00",
          "endTime": "17:00:00"
        },
        "contacts": [],
        "accessorials": [],
        "location": {
          "identifiers": [],
          "address": {
            "addressLines": [
              "3800 N Lamar Blvd",
              "Suite 210"
            ],
            "postalCode": "78756",
            "city": "Austin",
            "state": "TX",
            "country": "US"
          }
        }
      }
    ],
    "routeSegments": [
      {
        "id": "f65fb6f8-2a0d-4a05-a359-1059a9e30c55",
        "fromStopId": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a",
        "toStopId": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a"
      }
    ]
  },
  "attributes": [
    {
      "name": "attribute name",
      "values": [
        "string value 1",
        "string value 2"
      ]
    }
  ],
  "name": "shipmentName",
  "notes": "shipmentNotes"
}

In this response, you receive the project44-generated ID for the shipment (id). Store the project44-generated ID and use it to get shipment information.

This is an example of what could be returned in the response. Please, refer to the Booking API Reference Documentation from your project44 Technical Contact for more information on the fields and data that can be returned in this response.

Errors

If there was a problem with your request, you will receive one of the following error codes:

400 Bad Request
401 Unauthorized

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Fields and Objects

The table below describes only the minimum relevant fields of the API Request to create a shipment without an Ocean booking request. For more information on all fields, please, connect with your project44 Technical Contact for the Booking API Reference Documentation.

Field	Description
`identifiers`	The identifier used to distinguish the shipment. Include the `type` and `value`.
`routeInfo.stops.id`	The ID of the stop associated with the shipment. This will always be populated on response.
`routeInfo.stops.type`	The type of stop. Valid values include `PICKUP`, `PICKUP_DELIVERY`, `DELIVERY`, `PORT_OF_LOADING`, `PORT_OF_DISCHARGE`, `TRANSSHIPMENT_PORT`.
`routeInfo.stops.contacts.companyName`	The name of the Company with whom the Contact is associated.
`routeInfo.stops.location.address.addressLines`	The street name, number, direction, PO box, etc. Only three address lines are currently permitted. Use this if geocoordinates are not provided.
`routeInfo.stops.location.geocoordinates`	The latitude and longitude of the stop. Use only if the stop address is not provided.
`routeInfo.routeSegments.fromStopId`	The starting stop of this route segment.
`routeInfo.routeSegments.toStopId`	The ending stop of this route segment.

Create a Multi-modal shipment with an Ocean booking.

Requirements

At a minimum, have the following information

Shipment Identifier
Shipment Information/Data
- Pickup and delivery stop information for this shipment including
  - Stop ID
  - Stop Type (PICKUP and DELIVERY)
  - Company Name of the Stop Contact
  - Stop Location Address or Geocoordinates
  - Route Segment fromStopId and toStopId
Booking Information/Data
- Capacity Provider ID (SCAC, DOT_NUMBER, MC_NUMBER, P44_EU, SYSTEM, or P44_GLOBAL)
- Carrier Contact Name
- At Lease One Rate Identifier (SPOT_QUOTE or CONTRACT) and Source (SYSTEM, EXTERNAL, or UNKNOWN)
- Expiration Date and Time for the Request
- Route Segment IDs
- Shipment Details
  - Pickup & Delivery Stop IDs
  - Handling Unit Monetary Value, Quantity, Type, & Weight
  - Item identifiers
  - Load Identifiers
- Shipper Contact Information
  - Company Name of the Shipper Contact
- Shipping Details
  - Parties (SHIPPER, CONSIGNEE, BILL-TO NOTIFY)
  - Service Type (CONTAINER_YARD_TO_CONTAINER_YARD, CONTAINER_YARD_TO_DOOR, DOOR_TO_CONTAINER_YARD, DOOR_TO_DOOR)
  - Booking Type (LESS_THAN_CONTAINER_LOAD, FULL_CONTAINER_LOAD" "ROLL_ON_ROLL_OFF, OUT_OF_GAUGE)
  - Incoterm (EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DPU, DAP, DDP)
  - Cargo Measurements (when booking ROLL_ON_ROLL_OFF and LESS_THAN_CONTAINER_LOAD)
  - Container count (when booking FULL_CONTAINER_LOAD or OUT_OF_GAUGE)

Workflow

Complete these steps:

Please, connect with your project44 Technical Contact for the Booking API Reference Documentation.
Prepare a POST request to /services/booking/v1/shipments. For example,

JSON

{
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "SHIPMENT-12345"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        "id": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
        "type": "PICKUP",
        "arrivalDate": "2092-12-10",
        "location": {
          "address": {
            "addressLines": [
              "222 W. Merchandise Mart Plaza",
              "Suite 1744"
            ],
            "postalCode": "60654",
            "city": "Chicago",
            "state": "IL",
            "country": "US"
          }
        }
      },
      {
        "id": "195e34be-d7be-4b8d-ab1a-de18babe3e40",
        "type": "DELIVERY",
        "arrivalDate": "2092-12-12",
        "location": {
          "address": {
            "addressLines": [
              "3800 N Lamar Blvd",
              "Suite 210"
            ],
            "postalCode": "78756",
            "city": "Austin",
            "state": "TX",
            "country": "US"
          }
        }
      }
    ],
    "routeSegments": [
      {
        "id": "2063ccce-a97f-4409-b92a-48659880157d",
        "fromStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
        "toStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e"
      }
    ]
  },
  "attributes": [
    {
      "name": "attribute name",
      "values": [
        "string value 1",
        "string value 2"
      ]
    }
  ],
  "bookings": [
    {
      "attributes": [
        {
          "name": "attribute name",
          "values": [
            "string value 1",
            "string value 2"
          ]
        }
      ],
      "capacityProviderIdentifier": {
        "type": "SCAC",
        "value": "CODE"
      },
      "carrierContacts": [
        {
          "companyName": "Carrier Company Name",
          "givenName": "John",
          "familyName": "Hudson",
          "phoneNumber": "1223334445",
          "mobilePhoneNumber": "1223334444",
          "email": "j.hudson@carrier-company.project44.com"
        }
      ],
      "totalRate": {
        "currency": "USD",
        "amount": 3500
      },
      "rateIdentifiers": [
        {
          "source": "EXTERNAL",
          "type": "CONTRACT",
          "value": "contract-1234"
        }
      ],
      "expirationDateTime": "2092-12-01T08:30:00+00:00",
      "routeSegmentIds": [
        "2063ccce-a97f-4409-b92a-48659880157d"
      ],
      "notes": "Hello carrier! This is a note from the shipper, visible to you.",
      "shipmentDetails": [
        {
          "pickupStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
          "deliveryStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
          "handlingUnits": {
            "details": [
              {
                "monetaryValue": {
                  "currency": "USD",
                  "amount": 1200
                },
                "quantity": 10,
                "handlingUnitType": "PALLET",
                "stackable": true,
                "dimensions": {
                  "length": 48,
                  "width": 40,
                  "height": 40,
                  "unit": "IN"
                },
                "weight": {
                  "value": 2750,
                  "unit": "LB"
                }
              }
            ]
          },
          "items": [
            {
              "description": "Chicken meat",
              "identifiers": [
                {
                  "type": "SALES_ORDER",
                  "value": "SO-1a2b3c"
                }
              ],
              "unitQuantity": 12,
              "unitType": "BOX"
            }
          ],
          "description": "Temperature-Sensitive Goods",
          "identifiers": [
            {
              "type": "PURCHASE_ORDER",
              "value": "1234"
            }
          ],
          "accessorials": [
            {
              "code": "REFRIGERATED",
              "details": {
                "min": 32,
                "max": 40,
                "unit": "FAHRENHEIT"
              }
            }
          ]
        }
      ],
      "apiConfiguration": {
        "bookingWebhookName": "Shipper WebhookName"
      },
      "shipperContactInfo": {
        "companyName": "Shipper Company Name",
        "givenName": "Jennifer",
        "familyName": "Smith",
        "phoneNumber": "1223334445",
        "mobilePhoneNumber": "1223334444",
        "email": "j.smith@shipper-company.project44.com"
      },
      "shippingDetails": {
        "parties": [
          {
            "partyType": "SHIPPER",
            "contactInfo": {
              "companyName": "Shipper Company Name",
              "givenName": "Jennifer",
              "familyName": "Smith",
              "phoneNumber": "1223334445",
              "mobilePhoneNumber": "1223334444",
              "email": "j.smith@shipper-company.project44.com"
            },
            "addressInfo": {
              "addressLines": [
                "400 Montgomery St",
                "2nd Floor"
              ],
              "postalCode": "94104",
              "city": "San Francisco",
              "state": "CA",
              "country": "US"
            },
            "vatNumber": "vat-123"
          },
          {
            "partyType": "NOTIFY_PARTY",
            "contactInfo": {
              "companyName": "Notify Party Company Name",
              "givenName": "Henry",
              "familyName": "Jacobsen",
              "phoneNumber": "1223334445",
              "mobilePhoneNumber": "1223334444",
              "email": "h.jacobsen@notify-company.project44.com"
            },
            "addressInfo": {
              "addressLines": [
                "222 W. Merchandise Mart Plaza",
                "Suite 1744"
              ],
              "postalCode": "60654",
              "city": "Chicago",
              "state": "IL",
              "country": "US"
            },
            "vatNumber": "vat-234"
          }
        ],
        "serviceType": "DOOR_TO_DOOR",
        "bookingType": "FULL_CONTAINER_LOAD",
        "incoterm": "DAP",
        "cargoMeasurements": {
          "volume": {
            "value": 480,
            "unit": "CUBIC_FT"
          },
          "weight": {
            "value": 2500,
            "unit": "KG"
          },
          "dimensions": {
            "length": 20,
            "width": 6,
            "height": 4,
            "unit": "FT"
          }
        },
        "containerCount": {
          "reeferCount": {
            "fortyFootContainerCount": 1
          }
        },
        "accessorials": [
          {
            "code": "REFRIGERATED",
            "details": {
              "min": 32,
              "max": 40,
              "unit": "FAHRENHEIT"
            }
          }
        ]
      }
    }
  ]
}

Send the request.

Expected System Responses

The request is successfully submitted and confirmed when a 200 response is received.

JSON

{
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "SHIPMENT-12345"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        "id": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a",
        "type": "PICKUP",
        "arrivalDate": "2092-12-10",
        "arrivalAppointmentWindow": {
          "startTime": "10:15:00",
          "endTime": "12:45:00"
        },
        "contacts": [],
        "accessorials": [],
        "location": {
          "identifiers": [],
          "address": {
            "addressLines": [
              "222 W. Merchandise Mart Plaza",
              "Suite 1744"
            ],
            "postalCode": "60654",
            "city": "Chicago",
            "state": "IL",
            "country": "US"
          }
        }
      },
      {
        "id": "d0d8c4cd-681b-4707-9f38-631463ab60ad",
        "type": "DELIVERY",
        "arrivalDate": "2092-12-12",
        "arrivalAppointmentWindow": {
          "startTime": "15:15:00",
          "endTime": "17:00:00"
        },
        "contacts": [],
        "accessorials": [],
        "location": {
          "identifiers": [],
          "address": {
            "addressLines": [
              "3800 N Lamar Blvd",
              "Suite 210"
            ],
            "postalCode": "78756",
            "city": "Austin",
            "state": "TX",
            "country": "US"
          }
        }
      }
    ],
    "routeSegments": [
      {
        "id": "f65fb6f8-2a0d-4a05-a359-1059a9e30c55",
        "fromStopId": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a",
        "toStopId": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a"
      }
    ]
  },
  "attributes": [
    {
      "name": "attribute name",
      "values": [
        "string value 1",
        "string value 2"
      ]
    }
  ],
  "name": "shipmentName",
  "notes": "shipmentNotes",
  "bookings": [
    {
      "shipmentId": "b6308d53-9b7d-444e-85b7-02b744412781",
      "attributes": [
        {
          "name": "attribute name",
          "values": [
            "string value 1",
            "string value 2"
          ]
        }
      ],
      "capacityProviderIdentifier": {
        "type": "SCAC",
        "value": "CODE"
      },
      "carrierContacts": [
        {
          "companyName": "Carrier Company Name",
          "givenName": "John",
          "familyName": "Hudson",
          "phoneNumber": "1223334445",
          "mobilePhoneNumber": "1223334444",
          "email": "j.hudson@carrier-company.project44.com"
        }
      ],
      "totalRate": {
        "currency": "USD",
        "amount": 3500
      },
      "rateIdentifiers": [
        {
          "source": "EXTERNAL",
          "type": "CONTRACT",
          "value": "contract-1234"
        }
      ],
      "expirationDateTime": "2092-12-01T08:30:00+00:00",
      "routeSegmentIds": [
        "f65fb6f8-2a0d-4a05-a359-1059a9e30c55"
      ],
      "notes": "Hello carrier! This is a note from the shipper, visible to you.",
      "shipmentDetails": [
        {
          "pickupStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
          "deliveryStopId": "715cee06-71d1-40fa-b8d2-6aacac1f317e",
          "handlingUnits": {
            "details": [
              {
                "monetaryValue": {
                  "currency": "USD",
                  "amount": 1200
                },
                "quantity": 10,
                "handlingUnitType": "PALLET",
                "stackable": true,
                "dimensions": {
                  "length": 48,
                  "width": 40,
                  "height": 40,
                  "unit": "IN"
                },
                "weight": {
                  "value": 2750,
                  "unit": "LB"
                }
              }
            ]
          },
          "items": [
            {
              "description": "Chicken meat",
              "identifiers": [
                {
                  "type": "SALES_ORDER",
                  "value": "SO-1a2b3c"
                }
              ],
              "unitQuantity": 12,
              "unitType": "BOX"
            }
          ],
          "description": "Temperature-Sensitive Goods",
          "identifiers": [
            {
              "type": "PURCHASE_ORDER",
              "value": "1234"
            }
          ],
          "accessorials": [
            {
              "code": "REFRIGERATED",
              "details": {
                "min": 32,
                "max": 40,
                "unit": "FAHRENHEIT"
              }
            }
          ],
          "loadId": "d9d4b849-27b5-4a81-99b4-7e158082225c"
        }
      ],
      "apiConfiguration": {
        "bookingWebhookName": "Shipper WebhookName"
      },
      "shipperContactInfo": {
        "companyName": "Shipper Company Name",
        "givenName": "Jennifer",
        "familyName": "Smith",
        "phoneNumber": "1223334445",
        "mobilePhoneNumber": "1223334444",
        "email": "j.smith@shipper-company.project44.com"
      },
      "shippingDetails": {
        "parties": [
          {
            "partyType": "SHIPPER",
            "contactInfo": {
              "companyName": "Shipper Company Name",
              "givenName": "Jennifer",
              "familyName": "Smith",
              "phoneNumber": "1223334445",
              "mobilePhoneNumber": "1223334444",
              "email": "j.smith@shipper-company.project44.com"
            },
            "addressInfo": {
              "addressLines": [
                "400 Montgomery St",
                "2nd Floor"
              ],
              "postalCode": "94104",
              "city": "San Francisco",
              "state": "CA",
              "country": "US"
            },
            "vatNumber": "vat-123"
          },
          {
            "partyType": "NOTIFY_PARTY",
            "contactInfo": {
              "companyName": "Notify Party Company Name",
              "givenName": "Henry",
              "familyName": "Jacobsen",
              "phoneNumber": "1223334445",
              "mobilePhoneNumber": "1223334444",
              "email": "h.jacobsen@notify-company.project44.com"
            },
            "addressInfo": {
              "addressLines": [
                "222 W. Merchandise Mart Plaza",
                "Suite 1744"
              ],
              "postalCode": "60654",
              "city": "Chicago",
              "state": "IL",
              "country": "US"
            },
            "vatNumber": "vat-234"
          }
        ],
        "serviceType": "DOOR_TO_DOOR",
        "bookingType": "FULL_CONTAINER_LOAD",
        "incoterm": "DAP",
        "cargoMeasurements": {
          "volume": {
            "value": 480,
            "unit": "CUBIC_FT"
          },
          "weight": {
            "value": 2500,
            "unit": "KG"
          },
          "dimensions": {
            "length": 20,
            "width": 6,
            "height": 4,
            "unit": "FT"
          }
        },
        "containerCount": {
          "reeferCount": {
            "twentyFootContainerCount": 0,
            "fortyFootContainerCount": 1,
            "fortyFootHighCubeCount": 0
          }
        },
        "accessorials": [
          {
            "code": "REFRIGERATED",
            "details": {
              "min": 32,
              "max": 40,
              "unit": "FAHRENHEIT"
            }
          }
        ],
        "portsDetails": [
          [
            {
              "portType": "PORT_OF_LOADING",
              "estimatedDatetime": "2092-07-12T16:00:00+00:00"
            }
          ]
        ],
        "estimatedFinalDestinationDatetime": "2092-07-14T16:00:00",
        "cutOffDetails": {
          "cutOffDatetime": "2092-07-09T16:00:00+00:00",
          "vesselCutOffDatetime": "2092-07-11T16:00:00",
          "documentationCutOffDatetime": "2092-07-11T16:00:00"
        }
      },
      "id": "36e9d144-e151-4189-8275-b09bd6354550",
      "status": "BOOKED",
      "shipmentIdentifiers": [
        {
          "type": "CUSTOMER_REFERENCE",
          "value": "SHIPMENT-12345"
        }
      ],
      "routeSegments": [
        {
          "id": "f65fb6f8-2a0d-4a05-a359-1059a9e30c55",
          "fromStop": {
            "id": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a",
            "type": "PICKUP",
            "arrivalDate": "2092-12-10",
            "arrivalAppointmentWindow": {
              "startTime": "10:15:00",
              "endTime": "12:45:00"
            },
            "contacts": [],
            "accessorials": [],
            "location": {
              "identifiers": [],
              "address": {
                "addressLines": [
                  "222 W. Merchandise Mart Plaza",
                  "Suite 1744"
                ],
                "postalCode": "60654",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
              }
            }
          },
          "toStop": {
            "id": "e5afc2aa-758d-42ca-95a4-bac2c3c72a2a",
            "type": "PICKUP",
            "arrivalDate": "2092-12-10",
            "arrivalAppointmentWindow": {
              "startTime": "10:15:00",
              "endTime": "12:45:00"
            },
            "contacts": [],
            "accessorials": [],
            "location": {
              "identifiers": [],
              "address": {
                "addressLines": [
                  "222 W. Merchandise Mart Plaza",
                  "Suite 1744"
                ],
                "postalCode": "60654",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
              }
            }
          }
        }
      ],
      "carrierResponseMethod": "EDI",
      "bookingSourceMethod": "API",
      "transportationMode": "OCEAN",
      "masterShipmentId": "e8defadd-b97e-4184-a31f-2753bd4f3c35",
      "carrierProvidedIdentifiers": [
        {
          "type": "BOOKING_NUMBER",
          "value": "BN-1223334444"
        },
        {
          "type": "CARRIER_NAME",
          "value": "EON Ltd."
        },
        {
          "type": "CARRIER_SCAC",
          "value": "ELTD"
        },
        {
          "type": "VESSEL_NAME",
          "value": "Infinity"
        },
        {
          "type": "VOYAGE_NUMBER",
          "value": "117"
        }
      ]
    }
  ],
  "id": "b6308d53-9b7d-444e-85b7-02b744412781"
}

In this response, you receive the project44-generated ID for the shipment (id) and the booking (booking.id). Store the project44-generated ID, and use the shipment ID to get shipment information and use the booking ID to get tender/booking updates and to cancel tender/booking requests.

Errors

If there was a problem with your request, you will receive one of the following error codes:

400 Bad Request
401 Unauthorized

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Fields and Objects

The table below describes only the minimum relevant fields of the API Request to create a shipment with an Ocean booking request. For more information on all fields, please, connect with your project44 Technical Contact for the Booking API Reference Documentation.

Field	Description
`identifiers`	The identifier used to distinguish the shipment. Include the `type` and `value`.
`routeInfo.stops.id`	The ID of the stop associated with the shipment. This will always be populated on response.
`routeInfo.stops.type`	The type of stop. Valid values include `PICKUP`, `PICKUP_DELIVERY`, `DELIVERY`, `PORT_OF_LOADING`, `PORT_OF_DISCHARGE`, `TRANSSHIPMENT_PORT`.
`routeInfo.stops.contacts.companyName`	The name of the Company with whom the Contact is associated.
`routeInfo.stops.location.address.addressLines`	The street name, number, direction, PO box, etc. Only three address lines are currently permitted. Use this if geocoordinates are not provided.
`routeInfo.stops.location.geocoordinates`	The latitude and longitude of the stop. Use only if the stop address is not provided.
`routeInfo.routeSegments.fromStopId`	The starting stop of this route segment.
`routeInfo.routeSegments.toStopId`	The ending stop of this route segment.
`shippingDetails.parties`	Information for the involved parties. Valid values are `SHIPPER`, `CONSIGNEE`, `BILL-TO NOTIFY`.
`shippingDetails.serviceType`	The type of shipping service being provided. Valid values are `CONTAINER_YARD_TO_CONTAINER_YARD`, `CONTAINER_YARD_TO_DOOR`, `DOOR_TO_CONTAINER_YARD`, `DOOR_TO_DOOR`.
`shippingDetails.bookingType`	The type of booking. Valid values are `LESS_THAN_CONTAINER_LOAD`, `FULL_CONTAINER_LOAD" "ROLL_ON_ROLL_OFF`, `OUT_OF_GAUGE`.
`shippingDetails.incoterm`	International Commercial Terms. Valid values are `EXW`, `FCA`, `FAS`, `FOB`, `CFR`, `CIF`, `CPT`, `CIP`, `DPU`, `DAP`, `DDP`.
`shippingDetails.cargoMeasurements`	Use when booking `ROLL_ON_ROLL_OFF` and `LESS_THAN_CONTAINER_LOAD`.
`shippingDetails.containerCount`	Use when booking `FULL_CONTAINER_LOAD` or `OUT_OF_GAUGE`.

Create an Ocean booking request for an existing Multi-modal shipment to send to a Carrier.

Requirements

At a minimum, have the following information:

Shipment ID. NOTE: This is different from the Shipment Identifier. The Shipment ID is returned in the response for shipment creation.
Capacity Provider ID (SCAC, DOT_NUMBER, MC_NUMBER, P44_EU, SYSTEM, or P44_GLOBAL)
Carrier Contact Name
At Lease One Rate Identifier (SPOT_QUOTE or CONTRACT) and Source (SYSTEM, EXTERNAL, or UNKNOWN)
Expiration Date and Time for the Request
Route Segment IDs
Shipment Details
- Pickup & Delivery Stop IDs
- Handling Unit Monetary Value, Quantity, Type, & Weight
- Load Identifiers
Shipper Contact Information
- Shipper Contact Name
Shipping Details
- Parties (SHIPPER, CONSIGNEE, BILL-TO NOTIFY)
- Service Type (CONTAINER_YARD_TO_CONTAINER_YARD, CONTAINER_YARD_TO_DOOR, DOOR_TO_CONTAINER_YARD, DOOR_TO_DOOR)
- Booking Type (LESS_THAN_CONTAINER_LOAD, FULL_CONTAINER_LOAD" "ROLL_ON_ROLL_OFF, OUT_OF_GAUGE)
- Incoterm (EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DPU, DAP, DDP)
- Cargo Measurements (when booking ROLL_ON_ROLL_OFF and LESS_THAN_CONTAINER_LOAD)
- Container count (when booking FULL_CONTAINER_LOAD or OUT_OF_GAUGE)

Workflow

Complete these steps:

Please, connect with your project44 Technical Contact for the Booking API Reference Documentation.
Prepare a POST request to /services/booking/v1/shipments. For example,

JSON

{
  "attributes": [
    {
      "name": "attribute name",
      "values": [
        "string value 1",
        "string value 2"
      ]
    }
  ],
  "capacityProviderIdentifier": {
    "type": "SCAC",
    "value": "CODE"
  },
  "carrierContacts": [
    {
      "companyName": "Carrier Company Name",
      "givenName": "John",
      "familyName": "Hudson",
      "email": "j.hudson@carrier-company.project44.com"
    }
  ],
  "totalRate": {
    "currency": "USD",
    "amount": 3500
  },
  "rateIdentifiers": [
    {
      "source": "EXTERNAL",
      "type": "CONTRACT",
      "value": "contract-1234"
    }
  ],
  "expirationDateTime": "2092-12-01T08:30:00+00:00",
  "routeSegmentIds": [
    "3379b487-22ed-4459-bbe9-165e6708e7bd"
  ],
  "shipmentDetails": [
    {
      "pickupStopId": "bbd92c9c-6626-4636-b16f-d9cceb9d4e4d",
      "deliveryStopId": "8557cb6d-c7d0-4cb3-aa41-e4df0553c9d5",
      "handlingUnits": {
        "details": [
          {
            "monetaryValue": {
              "currency": "USD",
              "amount": 1200
            },
            "quantity": 10,
            "handlingUnitType": "PALLET",
            "stackable": true,
            "dimensions": {
              "length": 48,
              "width": 40,
              "height": 40,
              "unit": "IN"
            },
            "weight": {
              "value": 2750,
              "unit": "LB"
            }
          }
        ]
      },
      "description": "Temperature-Sensitive Goods",
      "identifiers": [
        {
          "type": "PURCHASE_ORDER",
          "value": "1234"
        }
      ],
      "accessorials": [
        {
          "code": "REFRIGERATED",
          "details": {
            "min": 32,
            "max": 40,
            "unit": "FAHRENHEIT"
          }
        }
      ]
    }
  ],
  "apiConfiguration": {
    "bookingWebhookName": "Shipper WebhookName"
  },
  "shipperContactInfo": {
    "companyName": "Shipper Company Name",
    "givenName": "Jennifer",
    "familyName": "Smith",
    "email": "j.smith@shipper-company.project44.com"
  },
  "shippingDetails": {
    "parties": [
      {
        "partyType": "SHIPPER",
        "contactInfo": {
          "companyName": "Shipper Company Name",
          "givenName": "Jennifer",
          "familyName": "Smith",
          "email": "j.smith@shipper-company.project44.com"
        },
        "addressInfo": {
          "addressLines": [
            "400 Montgomery St",
            "2nd Floor"
          ],
          "postalCode": "94104",
          "city": "San Francisco",
          "state": "CA",
          "country": "US"
        }
      },
      {
        "partyType": "NOTIFY_PARTY",
        "contactInfo": {
          "companyName": "Notify Party Company Name",
          "givenName": "Henry",
          "familyName": "Jacobsen",
          "email": "h.jacobsen@notify-company.project44.com"
        },
        "addressInfo": {
          "addressLines": [
            "222 W. Merchandise Mart Plaza",
            "Suite 1744"
          ],
          "postalCode": "60654",
          "city": "Chicago",
          "state": "IL",
          "country": "US"
        }
      }
    ],
    "serviceType": "DOOR_TO_DOOR",
    "bookingType": "FULL_CONTAINER_LOAD",
    "incoterm": "DAP",
    "containerCount": {
      "reeferCount": {
        "fortyFootContainerCount": 1
      }
    },
    "accessorials": [
      {
        "code": "REFRIGERATED",
        "details": {
          "min": 32,
          "max": 40,
          "unit": "FAHRENHEIT"
        }
      }
    ]
  }
}

Send the request.

Expected System Responses

The request is successfully submitted and confirmed when a 200 response is received.

JSON

{
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "attributes": [
    {
      "name": "string",
      "values": [
        "string"
      ]
    }
  ],
  "capacityProviderIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "carrierContacts": [
    {
      "companyName": "string",
      "givenName": "string",
      "familyName": "string",
      "phoneNumber": "string",
      "mobilePhoneNumber": "string",
      "email": "user@example.com"
    }
  ],
  "totalRate": {
    "currency": "USD",
    "amount": 0
  },
  "rateIdentifiers": [
    {
      "source": "SYSTEM",
      "type": "SPOT_QUOTE",
      "value": "string"
    }
  ],
  "expirationDateTime": "2019-08-24T14:15:22Z",
  "routeSegmentIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "notes": "string",
  "shipmentDetails": [
    {
      "pickupStopId": "eff50f2a-8964-41f9-b45d-0a4f6f94e159",
      "deliveryStopId": "2ca57692-0523-4424-a638-167e5e26f7d3",
      "handlingUnits": {
        "details": [
          {
            "monetaryValue": {
              "currency": "USD",
              "amount": 0
            },
            "quantity": 0,
            "handlingUnitType": "BAG",
            "stackable": false,
            "dimensions": {
              "length": 0,
              "width": 0,
              "height": 0,
              "unit": "FT"
            },
            "weight": {
              "value": 0,
              "unit": "LB"
            }
          }
        ]
      },
      "items": [
        {
          "description": "string",
          "identifiers": [
            {
              "type": "CONTAINER_NUMBER",
              "value": "string"
            }
          ],
          "unitQuantity": 0,
          "unitType": "BAG"
        }
      ],
      "description": "string",
      "identifiers": [
        {
          "type": "AIR_WAYBILL",
          "value": "string"
        }
      ],
      "accessorials": [
        {
          "code": "REFRIGERATED",
          "details": {
            "min": 0,
            "max": 0,
            "unit": "CELSIUS"
          }
        }
      ],
      "loadId": "9fa4c9ea-0db7-4bb2-8f50-086d18a90403"
    }
  ],
  "apiConfiguration": {
    "bookingWebhookName": "string"
  },
  "shipperContactInfo": {
    "companyName": "string",
    "givenName": "string",
    "familyName": "string",
    "phoneNumber": "string",
    "mobilePhoneNumber": "string",
    "email": "user@example.com"
  },
  "shippingDetails": {
    "loadPreference": "FULL",
    "trailerType": "FLATBED",
    "trailerLength": {
      "value": 0,
      "unit": "FT"
    },
    "trailerVolume": {
      "value": 0,
      "unit": "CUBIC_FT"
    },
    "flatbedType": "CONESTOGA",
    "accessorials": [
      {
        "code": "REFRIGERATED",
        "details": {
          "min": 0,
          "max": 0,
          "unit": "CELSIUS"
        }
      }
    ]
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "PROCESSING",
  "shipmentIdentifiers": [
    {
      "type": "AIR_WAYBILL",
      "value": "string"
    }
  ],
  "routeSegments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "fromStop": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "type": "PICKUP",
        "arrivalDate": "2019-08-24",
        "arrivalAppointmentWindow": {
          "startTime": "14:15:22Z",
          "endTime": "14:15:22Z"
        },
        "contacts": [
          {
            "companyName": "string",
            "givenName": "string",
            "familyName": "string",
            "phoneNumber": "string",
            "mobilePhoneNumber": "string",
            "email": "user@example.com"
          }
        ],
        "accessorials": [
          {
            "code": "REFRIGERATED",
            "details": {
              "min": 0,
              "max": 0,
              "unit": "CELSIUS"
            }
          }
        ],
        "location": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "identifiers": [
            {
              "type": "AIRPORT_IATA",
              "value": "string"
            }
          ],
          "address": {
            "addressLines": [
              "string"
            ],
            "postalCode": "string",
            "city": "string",
            "state": "string",
            "country": "US"
          },
          "geoCoordinates": {
            "latitude": -90,
            "longitude": -180
          }
        }
      },
      "toStop": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "type": "PICKUP",
        "arrivalDate": "2019-08-24",
        "arrivalAppointmentWindow": {
          "startTime": "14:15:22Z",
          "endTime": "14:15:22Z"
        },
        "contacts": [
          {
            "companyName": "string",
            "givenName": "string",
            "familyName": "string",
            "phoneNumber": "string",
            "mobilePhoneNumber": "string",
            "email": "user@example.com"
          }
        ],
        "accessorials": [
          {
            "code": "REFRIGERATED",
            "details": {
              "min": 0,
              "max": 0,
              "unit": "CELSIUS"
            }
          }
        ],
        "location": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "identifiers": [
            {
              "type": "AIRPORT_IATA",
              "value": "string"
            }
          ],
          "address": {
            "addressLines": [
              "string"
            ],
            "postalCode": "string",
            "city": "string",
            "state": "string",
            "country": "US"
          },
          "geoCoordinates": {
            "latitude": -90,
            "longitude": -180
          }
        }
      }
    }
  ],
  "rejectionReason": "COST_NOT_AGREED",
  "carrierResponseMethod": "EMAIL",
  "automatedFailureReason": "ERROR_CREDENTIALS",
  "bookingSourceMethod": "API",
  "carrierRejectionNotes": "string",
  "transportationMode": "OCEAN",
  "masterShipmentId": "2e04ec4a-749a-4ef4-a452-b7dc8cca16aa",
  "carrierProvidedIdentifiers": [
    {
      "type": "AIR_WAYBILL",
      "value": "string"
    }
  ]
}

In this response, you receive the project44-generated booking ID (id). Store the project44-generated booking ID and use it to get tender/booking updates and to cancel tender/booking requests.

Errors

If there was a problem with your request, you will receive one of the following error codes:

400 Bad Request
401 Unauthorized
404 Not Found

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Fields and Objects

The table below describes only the minimum relevant fields of the API Request to create an Ocean booking request. For more information on all fields, please, connect with your project44 Technical Contact for the Booking API Reference Documentation.

Field	Description
`capacityProviderIdentifier`	Reference to the desired carrier to transport the shipment across the booking's specified route segments. Include the `type` (valid values are `SCAC`, `DOT_NUMBER`, `P44_EU`, `SYSTEM`, or `P44_GLOBAL`) and `value`.
`carrierContacts.companyName`	The name of the Company with whom the Contact is associated.
`rateIdentifiers`	A list of at least one identifier as reference to the original source of the rate applicable to the booking. Include the `source` (valid values are `SYSTEM`, `EXTERNAL`, or `UNKNOWN`), identifier `type` (valid values are `SPOT_QUOTE` or `CONTRACT`), and identifier `value`.
`expirationDateTime`	The datetime of expiration for this request from the shipper to the carrier. A timezone offset is required.
`routeSegmentIds`	A list of route-segment ids which apply to the booking.
`shipmentDetails.pickUpStopId`	The unique ID for the location where the handling unit should be picked up.
`shipmentDetails.deliveryStopId`	The unique ID for the location where the handling unit should be delivered.
`shipmentDetalis.handlingUnits.details.monetaryValue`	The monetary value of the handling unit. Include `currency` (valid values are `USD`, `CAD`, `MXN`, `EUR`, and `GBP`) and `amount`.
`shipmentDetalis.handlingUnits.details.quantity`	Quantity of the handling unit type that is specified in `shipmentDetails.handlingUnits.details.handlingUnitType`.
`shipmentDetalis.handlingUnits.details.handlingUnitType`	The packaging used to handle the unit during transport. Valid values include `BAG`, `BALE`, `BOX`, `BUCKET`, `BUNDLE`, `CAN`, `CARTON`, `CASE`, `COIL`, `CRATE`, `CYLINDER`, `DRUM`, `PAIL`, `PALLET`, `PIECES`, `REEL`, `ROLL`, `SKID`, `TOTE`, and `TUBE`.
`shipmentDetalis.handlingUnits.details.weight`	The weight of the handling unit. Take care that this should reference the per quantity weight of the chosen handling unit type. Include the `value` and `unit` (valid values are `LB` and `KG`).
`shipmentDetails.identifiers`	The identifiers that can identify this load. This could be, but not limited to, a shipment identifier such as a `BILL_OF_LADING` or an order-based identifier such as `PURCHASE_ORDER`. Include the `type` (valid values are `BILL_OF_LADING`, `BOOKING_NUMBER`, `CARRIER_SCAC`, `CONTAINER_ID`, `CUSTOMER_REFERENCE`, `DELIVERY_NUMBER`, `ORDER`, `PURCHASE_ORDER`, `TRACKING_NUMBER`, `TRAILER_ID`, `CARRIER_US_DOT_NUMBER`, `CARRIER_MC_NUMBER`, `SALES_ORDER`, `DRIVER_MOBILE_PHONE_NUMBER`, `VEHICLE_ID`, `LICENSE_PLATE`, `SENSITECH_DEVICE_ID`, `EMERSON_DEVICE_ID`, `TIVE_DEVICE_ID`, `CARRIER_MASTER_ID`, `CARRIER_NMC_ID`) and `value`.
`shipperContactInfo.companyName`	The name of the Company with whom the Contact is associated.
`shippingDetails.parties`	Information for the involved parties. Valid values are `SHIPPER`, `CONSIGNEE`, `BILL-TO NOTIFY`.
`shippingDetails.serviceType`	The type of shipping service being provided. Valid values are `CONTAINER_YARD_TO_CONTAINER_YARD`, `CONTAINER_YARD_TO_DOOR`, `DOOR_TO_CONTAINER_YARD`, `DOOR_TO_DOOR`.
`shippingDetails.bookingType`	The type of booking. Valid values are `LESS_THAN_CONTAINER_LOAD`, `FULL_CONTAINER_LOAD" "ROLL_ON_ROLL_OFF`, `OUT_OF_GAUGE`.
`shippingDetails.incoterm`	International Commercial Terms. Valid values are `EXW`, `FCA`, `FAS`, `FOB`, `CFR`, `CIF`, `CPT`, `CIP`, `DPU`, `DAP`, `DDP`.
`shippingDetails.cargoMeasurements`	Use when booking `ROLL_ON_ROLL_OFF` and `LESS_THAN_CONTAINER_LOAD`.
`shippingDetails.containerCount`	Use when booking `FULL_CONTAINER_LOAD` or `OUT_OF_GAUGE`.

Create a Shipment or Request a Booking

Create a Multi-modal Shipment Without a Booking Request

Requirements

Workflow

Expected System Responses

Errors

Fields and Objects

Create a Multi-modal Shipment Containing an Ocean Booking Request

Requirements

Workflow

Expected System Responses

Errors

Fields and Objects

Create an Ocean Booking for a Multi-modal Shipment

Requirements

Workflow

Expected System Responses

Errors

Fields and Objects

Was this helpful?