Transportation Plans

The transportation plan API is provided to model the movement of goods across multiple modes of transportation. An example would be a container that is offloaded from a ship and delivered to a facility as a drayage mode, then unpacked and loaded into a dry van as a transload, and finally transported to the end customer as a full truck load. The underlying data model contains the following primary data objects:

  • Transportation Plan - the top level object with meta data and is the parent of stages
  • Service - defines a service provider like a transload, storage, or terminal
  • Shipment - the v2/shipment model
  • Stage - container for services and legacy shipments

The advantage of using the transportation plan model is it allows aggregation across all of the stages to do things like calculate the total cost of moving goods across multiple modes and service providers, assign different carries to different stages of the movement of goods, and allocate different financial accounting to the different stages of the movement.

Creating transportation plans via the UI

Let’s explore how to implement a movement of goods that includes drayage → transload → full truck load to see how the transportation plan API is used to model it. To begin, here is how the UI is used to create a transportation plan, seen on the action panel below.

Next, we want to create a transload stage following the drayage move. Which if performed from the UI would be done by adding a new stage the drayage stage.

A modal is presented when adding a new stage and in our case we want to create a transload stage.

Details are provided for the transload service provider and the stage is created.

Although the UI implies the drayage stage has been created, in actuality it is created just prior to creating the transload stage. First, a multi-stage shipment is created with a drayage stage, and then the transload stage is created. Resulting in both stages being displayed in the action panel UI for the drayage shipment.

Adding an additional full truckload stage is performed the same way as adding a transload stage except FTL is selected in the model instead of Transload.

Using the API to create a multi-stage shipment

To perform the same actions using the API start by creating a drayage mode v2/shipment using the existing APIs to POST a v2/shipment. Documentation can be found here.

Create a Transportation Plan shell

Note!

The current routes will be updated shortly and usage of the current transportation plan routes will be supported going forward. The changes are in naming only, not functionality. The intention is to avoid ambiguity between the current shipment model and the new transportation plan model. The name changes will include the following:

  • All /shipment routes will be renamed to /transportation-plan
  • legacy_shipment_id will be renamed shipment_id
  • legacy_shipment will be renamed shipment

The examples below use the current naming convention for the routes and response bodies that will be updated in the future.

Create a transportation plan using the POST /shipments route to act as the container for the stages we will be creating. There are no required parameters in the request body and in this example none were provided. The resulting response body contains id: of the newly created transportation plan.

Copy
Copied
{
    "created_at": "2022-12-02T18:39:07.256021+00:00",
    "updated_at": "2022-12-02T18:39:07.256021+00:00",
    "name": null,
    "archived": false,
    "instructions": null,
    "references": [],
    "mode_specific_data": [],
    "id": "01GKA255FRSJ7Y1251HE5Q78DR",
    "reference_id": "QQBRR0",
    "created_by": {
        "tenant_id": "a54ef012-77d4-44a0-8ba5-115b09b655be",
        "user_id": "f0b979c9-28e2-41d6-883e-cb1f5c320bb4"
    },
    "overall_status": "DRAFT",
    "stages": [],
    "contacts": [],
    "items": [],
    "stops": [],
    "customer": null
}

Add the drayage shipment as the first stage

Add the drayage shipment created previously as the first stage of the transportation plan by using the GET /shipments/{shipment_id}/legacy-shipment-stages route providing the newly created transportation plan id: as the path parameter and the drayage shipment id in the body of the request as the legacy_shipment_id. The response body contains details of the newly created stage.

Copy
Copied
{
    "id": "01GKA2E6TFS7KPYJZPK6T4B5GY",
    "shipment_id": "01GKA255FRSJ7Y1251HE5Q78DR",
    "stage_type": "LEGACY_SHIPMENT",
    "directly_dependent_stages": [],
    "directly_depends_on_stages": [],
    "legacy_shipment_id": "b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e",
    "legacy_shipment": {
        "id": "b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e",
        "resource_type": "shipment",
        "self_link": "https://dev-api.shipwell.com/v2/shipments/b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e/"
    }
}

Use the GET /shipments/{shipment_id)/stages route with the transportation plan id: as the path parameter to review the stages of the transportation plan and note that the response contains the drayage legacy shipment added.

Copy
Copied
{
    "data": [
        {
            "id": "01GKA2E6TFS7KPYJZPK6T4B5GY",
            "shipment_id": "01GKA255FRSJ7Y1251HE5Q78DR",
            "stage_type": "LEGACY_SHIPMENT",
            "directly_dependent_stages": [],
            "directly_depends_on_stages": [],
            "legacy_shipment_id": "b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e",
            "legacy_shipment": {
                "id": "b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e",
                "resource_type": "shipment",
                "self_link": "https://dev-api.shipwell.com/v2/shipments/b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e/"
            }
        }
    ]
}

Add a transload stage

Adding a transload stage is a multi-step process. First getting a list of service providers, then create a transload service, and finally assign the created transload service to a multi-stage shipment stage while defining the stage’s dependency.

Get a list of service providers

To get a list of potential service providers use the GET /v2/service-providers/ route to identify the id: of the desired service provider with capabilities: ["TRANSLOAD"]. Here is an abbreviated example of the response for a service provider:

Copy
Copied
{
            "id": "01GCFAZ41VG6DC08F6CZEN4P5P",
            "created_at": "2022-09-08T19:59:25.755080Z",
            "updated_at": "2022-09-08T19:59:25.756034Z",
            "name": "Brent Testing",
            "mailing_address": {
                "id": "4fcdb651-f0d9-4111-a333-8b980e463187",
                "address_1": "8901 Brook Rd",
                "address_2": null,
                "city": "Glen Allen",
                "state_province": "VA",
                "postal_code": "23060",
                "country": "US",
                "phone_number": null,
                "formatted_address": "8901 Brook Rd, Glen Allen, VA 23060, US",
                "created_at": "2022-09-08T19:59:25.461200Z",
                "updated_at": "2022-09-08T19:59:25.602573Z"
            },
            "tags": [],
            "capabilities": [
                "TRANSLOAD"
            ],
            "notes": null,
            "billing_email": null,
            "status": "ACTIVE",
            "resource_type": "service-provider",
            "self_link": "http://dev-api.shipwell.com/v2/service-providers/01GCFAZ41VG6DC08F6CZEN4P5P"
        }

Create a transload service

Use the id in the response body from the POST /shipments route we started with as the shipment_id and use the id from the POST /services/transload above as the service_id for the POST /shipments/{shipment_id}/services/{service_id} route to associate the service with the multi-stage shipment. In the body below the dependency is defined. We’ll make this transload service dependent on the legacy shipment stage created earlier. Note the directly_depends_on_stages below reference the id from the legacy shipment stage.

Copy
Copied
{
    "directly_depends_on_stages": ["01GKA2E6TFS7KPYJZPK6T4B5GY"]
}

Use the GET /shipments/{shipment_id)/stages to confirm the new transload stage is listed

Copy
Copied
{
            "id": "01GKA2E6TFS7KPYJZPK6T4B5GY",
            "shipment_id": "01GKA255FRSJ7Y1251HE5Q78DR",
            "stage_type": "LEGACY_SHIPMENT",
            "directly_dependent_stages": [
                "01GKAATMFA9A2XHW8CE334CPE0"
            ],
            "directly_depends_on_stages": [],
            "legacy_shipment_id": "b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e",
            "legacy_shipment": {
                "id": "b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e",
                "resource_type": "shipment",
                "self_link": "https://dev-api.shipwell.com/v2/shipments/b901aaa2-e9e9-4621-8de8-89f8e5ceaa2e/"
            }
        },
        {
            "id": "01GKAATMFA9A2XHW8CE334CPE0",
            "shipment_id": "01GKA255FRSJ7Y1251HE5Q78DR",
            "stage_type": "SERVICE",
            "directly_dependent_stages": [],
            "directly_depends_on_stages": [
                "01GKA2E6TFS7KPYJZPK6T4B5GY"
            ],
            "service": {
                "service_type": "TRANSLOAD",
                "reference_id": "JENHSG",
                "custom_data": null,
                "location": {
                    "address": {
                        "country": "US",
                        "line_1": "8901 Three Chopt Rd",
                        "line_2": null,
                        "line_3": null,
                        "locality": "Richmond",
                        "postal_code": "23229",
                        "region": "VA",
                        "urbanization": null,
                        "residential": false,
                        "geolocation": null
                    },
                    "location_name": "Brent Testing",
                    "location_number": "PA-1",
                    "system_id": "Brent Testing, PA-1",
                    "company_name": "Brent Testing",
                    "location_type": "OTHER",
                    "timezone": "America/Chicago"
                },
                "service_provider": {
                    "provider_id": "01GESC9P9J5V0YW33JW7647Z6N",
                    "identification_codes": [],
                    "name": "Brent Testing"
                },
                "actual_datetimes": null,
                "provider_rate": null,
                "customer_rate": null,
                "references": [],
                "id": "01GKAASHXVS1ZKVR90RH7BAFJY"
            }
        }

Adding the full truck load stage

The final full truckload stage is added the same way the drayage stage was added to the transportation plan in the fist step of this developer guide and is left as an exercise for the developer to complete this example.

Copyright © Shipwell 2023. All right reserved.