Create a Shipment

Create an Ocean shipment by using an API endpoint to add the shipment to project44's network and send tracking information about the shipment.

Create an Ocean Shipment

Create an Ocean shipment to be tracked in project44's network using at least one shipment identifier and exactly one Carrier SCAC. This step is necessary before tracking of an Ocean shipment can start.

Requirements

Have the following information:

One shipment ID: BILL_OF_LADING or BOOKING_NUMBER.
And exactly one CARRIER_SCAC. View SCACs for in-network Ocean carriers.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/shipments/tracking.
Add the shipment identifiers to the request schema. For example,

Copy

Copied

{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ]
}

note

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Send the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the minimum response schema:

Copy

Copied

{
  "id": "93294f58-f87a-48e0-9f68-7d3f6e0aaa2f",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ]
}

In this response you receive the identifiers used in the request (BILL_OF_LADING or BOOKING_NUMBER and CARRIER_SCAC) plus the UUID (id) and all related container CONTAINER_IDs and ids. Once the shipment is added to project44’s system, we will find related shipments. You will see the related shipment information in the relatedShipments array in the GET requests.

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

note

Store the id. Use the id to get shipment tracking updates.

Errors

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

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

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 for tracking and the fields returned with the API Response 200 OK.

Field	Description
`id`	The Master Shipment ID of the shipment. This field is not required to create the shipment. It is returned in the `200` OK response when you create the shipment. Store the Master Shipment ID and use it to create or update a PUSH configuration (link to section).
`identifiers`	The shipment ID (different from the master shipment ID above) is necessary for shipment creation and for other actions including getting tracking information, updating a shipment, and deleting a shipments.
`identifiers.type`	The type of identifier for the shipment. For shipment creation, you must include at least one `BILL_OF_LADING` (unique identifier given to you by the Ocean carrier. Bills of Lading (BOLs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) or `BOOKING_NUMBER` (unique identifiers given to you by the Ocean carrier. Booking Numbers (BNs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) AND exactly one `CARRIER_SCAC` (the carrier's Standard Carrier Alpha Code, a unique identification number for a specific carrier, usually two to four letters long.)
`identifiers.value`	The value for the identifiers for the shipment.

Create an Ocean Shipment and Include Shipment Attributes

Create an Ocean shipment to be tracked in project44's network and include shipment attributes. You can tag shipments with attributes, a customized key:value pair, at any point in the shipment's lifecycle.

Requirements

Have the following information:

One shipment ID: BILL_OF_LADING or BOOKING_NUMBER.
Exactly one CARRIER_SCAC. View SCACs for in-network Ocean carriers.
The names and values for each shipment attributes.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/shipmentattributedefinitions. This step is necessary to create the attributes (if they do not already exist in project44’s system) before creating a shipment with your preferred attributes. For example,

Copy

Copied

{

"name": "Attribute Name"

}

Add the attribute name to the request body in the next step.
Prepare a POST request to /api/v4/shipments/tracking.
Add the shipment identifiers to the request schema. For example,

Copy

Copied

{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "attributes": [
    {
      "name": "string",
      "value": "string",
      "values": [
        "string"
      ]
    }
  ]
}

note

Submit the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the response schema:

Copy

Copied

{
  "id": "93294f58-f87a-48e0-9f68-7d3f6e0aaa2f",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "attributes": [
    {
      "name": "string",
      "value": "string",
      "values": [
        "string"
      ]
    }
  ],
  "relatedShipments": [
    {
      "id": "string",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "string"
        }
      ]
    },
    {
      "id": "string",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "string"
        }
      ]
    },
    {
      "id": "string",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "string"
        }
      ]
    }
  ]
}

In the response you receive the identifiers (BILL_OF_LADING or BOOKING_NUMBER and CARRIER_SCAC) and the shipment attributes (attributes array) used in the request. Plus you will receive the Master Shipment ID (id) and all related container CONTAINER_IDs and ids.

This example only shows the minimum relevant information. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

note

Store the Master Shipment ID. Use the Master Shipment ID to get shipment tracking updates.

Errors

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

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

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

Fields & Objects

Field	Description
`id`	The Master Shipment ID of the shipment. This field is not required to create the shipment. It is returned in the `200 OK` response when you create the shipment. Store the Master Shipment ID and use it to create or update a PUSH configuration (link to section) or get shipment tracking information (link to section).
`identifiers`	The shipment ID (different from the master shipment ID above) is necessary for shipment creation and for other actions including getting tracking information, updating a shipment, and deleting a shipments.
`identifiers.type`	The type of identifier for the shipment. For shipment creation, you must include at least one `BILL_OF_LADING` (unique identifier given to you by the Ocean carrier. Bills of Lading (BOLs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) or `BOOKING_NUMBER` (unique identifiers given to you by the Ocean carrier. Booking Numbers (BNs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) AND exactly one `CARRIER_SCAC` (the carrier's Standard Carrier Alpha Code, a unique identification number for a specific carrier, usually two to four letters long.)
`identifiers.value`	The value for the identifiers for the shipment.
`attributes`	An optional user-defined set of custom attributes to associate with this shipment.
`attributes.name`	The key (name) for the custom attribute. Must be unique.
`attributes.value`	This field has been deprecated. While it will return in the response, you do not hard code to it.
`attributes.values`	An array of the values for the custom attribute.

Create an Ocean Shipment with a Container ID

Only use this workflow if you do not have a BILL_OF_LADING or a BOOKING_NUMBER for your shipment.

note

This method is not recommended as not all carriers support shipment creation with a CONTAINER_ID.

Requirements

Have the following information available:

A CONTAINER_ID.
Exactly one CARRIER_SCAC. View SCACs for in-network Ocean carriers.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/shipments/tracking.
Add the CONTAINER_ID to the identifiers array in the request schema.

Copy

Copied

 	{
  "identifiers": [
    {
      "type": "CONTAINER_ID",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ]
}

note

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Submit the request.

Expected Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the response schema:

Copy

Copied

{
  "id": "93294f58-f87a-48e0-9f68-7d3f6e0aaa2f",
  "identifiers": [
    {
      "type": "CONTAINER_ID",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ]
}

In this response you receive the identifiers used in the request (CONTAINER_ID and CARRIER_SCAC) plus the Master Shipment ID (id) of the shipment.

note

Store the Master Shipment ID. Use the Master Shipment ID to get shipment tracking updates.

Errors

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

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

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

Fields & Objects

The table below describes only the minimum relevant fields of the API Request to create a shipment for tracking and the fields returned with the API Response 200 OK.

Field	Description
`id`	The Master Shipment ID of the shipment. This field is not required to create the shipment. It is returned in the `200 OK` response when you create the shipment. Store the Master Shipment ID and use it to create or update a PUSH configuration (link to section).
`identifiers`	The shipment ID (different from the master shipment ID above) is necessary for shipment creation and for other actions including getting tracking information, updating a shipment, and deleting a shipments.
`identifiers.type`	The type of identifier for the shipment. For shipment creation, you must include at least one `BILL_OF_LADING` (unique identifier given to you by the Ocean carrier. Bills of Lading (BOLs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) or `BOOKING_NUMBER` (unique identifiers given to you by the Ocean carrier. Booking Numbers (BNs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) AND exactly one `CARRIER_SCAC` (the carrier's Standard Carrier Alpha Code, a unique identification number for a specific carrier, usually two to four letters long.)
`identifiers.value`	The value for the identifiers for the shipment.

Create an Ocean Shipment and Track Specific Containers

Only use this workflow if you want to track specific containers related to your shipment instead of all containers related to your shipment.

Requirements

Have the following information available:

One of the following shipment IDs: BILL_OF_LADING or BOOKING_NUMBER.
Exactly one CARRIER_SCAC. View SCACs for in-network Ocean carriers.
A CONTAINER_ID for each related container.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/shipments/tracking.
Add the shipment identifiers to the identifiers array in the request schema.
Add the CONTAINER_ID for each related container to the relatedShipments array in the request schema. The completed request schema should look like this:

Copy

Copied

{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    },
    {
      "type": "CONTAINER_ID",
      "value": "string"
    },
    {
      "type": "CONTAINER_ID",
      "value": "string"
    },
    {
      "type": "CONTAINER_ID",
      "value": "string"
    }
  ]
}

note

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Submit the request.

Expected Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the response schema:

Copy

Copied

{
  "id": "93294f58-f87a-48e0-9f68-7d3f6e0aaa2f",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    },
    {
      "type": "CONTAINER_ID",
      "value": "string"
    },
    {
      "type": "CONTAINER_ID",
      "value": "string"
    },
    {
      "type": "CONTAINER_ID",
      "value": "string"
    }
  ]
}

In this response you receive the identifiers used in the request (BILL_OF_LADING or BOOKING_NUMBER and CARRIER_SCAC) plus the Master Shipment ID (id) and all specified related container CONTAINER_IDs and ids.

note

Store the Master Shipment ID. Use the Master Shipment ID to get shipment tracking updates.

Errors

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

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

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

Fields & Objects

The table below describes only the minimum relevant fields of the API Request to create a shipment for tracking and the fields returned with the API Response 200 OK.

Field	Description
`id`	The Master Shipment ID of the shipment. This field is not required to create the shipment. It is returned in the `200 OK` response when you create the shipment. Store the Master Shipment ID and use it to create or update a PUSH configuration (link to section).
`identifiers`	The shipment ID (different from the master shipment ID above) is necessary for shipment creation and for other actions including getting tracking information, updating a shipment, and deleting a shipments.
`identifiers.type`	The type of identifier for the shipment. For shipment creation, you must include at least one `BILL_OF_LADING` (unique identifier given to you by the Ocean carrier. Bills of Lading (BOLs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) or `BOOKING_NUMBER` (unique identifiers given to you by the Ocean carrier. Booking Numbers (BNs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) AND exactly one `CARRIER_SCAC` (the carrier's Standard Carrier Alpha Code, a unique identification number for a specific carrier, usually two to four letters long.)
`identifiers.value`	The value for the identifiers for the shipment.

Create a Shipment

Create an Ocean Shipment

Requirements

Workflow

note

Expected System Response

note

Errors

Fields and Objects

Create an Ocean Shipment and Include Shipment Attributes

Requirements

Workflow

note

Expected System Response

note

Errors

Fields & Objects

Create an Ocean Shipment with a Container ID

note

Requirements

Workflow

note

Expected Response

note

Errors

Fields & Objects

Create an Ocean Shipment and Track Specific Containers

Requirements

Workflow

note

Expected Response

note

Errors

Fields & Objects

Was this page helpful?