Retrieving Applicable Contracts for a Shipment

Overview

Learn the best practices on how to lookup or retrieve applicable carrier contracts by shipment using the Shipwell platform's API.

Understanding Carrier Contracts and Contract Lanes

What is a Carrier Contract?

A carrier contract is a formal agreement between a shipper and a carrier that outlines the terms and conditions for transporting goods. It typically includes:

Rate Structure : Base rates and additional charges
Service Levels : Expected delivery times and service quality
Geographic Coverage : Specific routes and regions
Duration : Contract start and end dates
Special Terms : Fuel surcharges, accessorials, and other conditions

What is a Contract Lane?

A contract lane represents a specific route or corridor defined within a carrier contract. The term "lane" in logistics refers to a transportation route between two points, similar to a lane on a highway that connects two destinations. Each lane includes:

Origins and Destinations : Specific pickup and delivery locations (also called stops)
Distance : Miles or kilometers between stops
Rate Details : Specific rates for the lane
Service Requirements : Special handling instructions

How Contract Lanes Affect Pricing

Contract lanes impact pricing because they reflect the transportation costs between specific locations. Here's an example:

Example: Washington DC to New York vs. DC to Los Angeles

DC to New York Lane
- Distance: ~230 miles (example)
- Rate: $1.50 USD per mile
- Total: $345 USD
- Fuel Surcharge: $60 USD
- Final Cost : $405 USD
DC to Los Angeles Lane
- Distance: ~2,300 miles (example)
- Rate: $1.20 USD per mile (bulk discount)
- Total: $2,760 USD
- Fuel Surcharge: $552 USD
- Final Cost : $3,312 USD

Key Factors Affecting Lane Pricing

Distance : Longer distances often have better per-mile/kilometer rates due to bulk discounts
Route Complexity : Urban routes may have higher costs due to congestion
Demand : High-demand routes can command higher rates
Special Requirements : Hazmat, temperature-controlled, or over-sized cargo can increase costs
Fuel Costs : Longer routes may have higher fuel surcharges
Turn Time : Quick turnaround times may incur additional charges

The Shipwell platform's calculate-charge-items API endpoint takes these lane-specific factors into account (learn more here).

How Carrier Contracts and Lanes Work Together

Contract Level : Defines general terms and carrier relationships
Lane Level : Specifies rates and terms for specific routes
Shipment Level : Applies contract and lane details to individual shipments

Prerequisite: Authenticate and Receive API Token

Authenticate to the API using these steps.

Note

Authorization HTTP headers in API requests, e.g. Authorization: YOUR_AUTHORIZATION_HEADER, typically take the form of Authorization: Token <user-token>. For more information on API authentication, navigate to the Authenticate documentation.

Steps (By Shipment Id)

Retrieve Applicable Contracts by Shipment Id

Retrieve a list of contracts applicable to a specific shipment based on the shipment identifier (aka shipment_id) using POST /v2/contracts/applicable-contracts (see API reference).

Tip

The body or payload of the POST /v2/contracts/applicable-contracts request has a request_type property that determines if the applicable contracts are looked up BY_SHIPMENT (aka "by shipment id") or BY_VALUE (aka by the shipment object details or value like weights, origin, destination, etc.).

For example, "request_type": "BY_SHIPMENT" or "request_type": "BY_VALUE".

Example request (BY_SHIPMENT)

curlpythonjavajavascript

Copy

Copied

curl -X POST \
  https://sandbox-api.shipwell.com/v2/contracts/applicable-contracts \
  -H 'Authorization: Token YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d ' {
    "request_type": "BY_SHIPMENT",
    "shipment_id": "b2888076-051c-46f7-bd75-c96720f94a9e"
  }'

Copy

Copied

import requests

shipment_id = "b2888076-051c-46f7-bd75-c96720f94a9e"

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = f"https://{host}{base_path}/contracts/applicable-contracts"

headers = {
    "Authorization": "Token YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

data = {
   "request_type": "BY_SHIPMENT",
   "shipment_id": shipment_id
}

response = requests.post(target_url, headers=headers, json=data)
print(response.json())

Copy

Copied

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.RequestBody;
import okhttp3.MediaType;

OkHttpClient client = new OkHttpClient();

// Configuration
String shipmentId = "b2888076-051c-46f7-bd75-c96720f94a9e";

String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  basePath +
  "/contracts/applicable-contracts";
String requestBody = String.format("""
            {
                "request_type": "BY_SHIPMENT",
                "shipment_id": "%s"
            }
            """, shipmentId);

// Build and execute the request
Request request = new Request.Builder()
    .url(targetUrl)
    .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
    .header("Authorization", "Token YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .build();

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) {
        throw new IOException("Unexpected code " + response);
    }
    System.out.println(response.body().string());
}

Copy

Copied

const shipmentId = "b2888076-051c-46f7-bd75-c96720f94a9e";
const payload = {
    "request_type": "BY_SHIPMENT",
    "shipment_id": shipmentId
};


const basePath = "/v2";
const host = "sandbox-api.shipwell.com"
const targetUrl = `https://${host}${basePath}/contracts/applicable-contracts`;

const resp = await fetch(
    targetUrl,
    {
        method: "POST",
        headers: {
            "Authorization": "Token YOUR_ACCESS_TOKEN",
            "Content-Type": "application/json"
        },
        body: JSON.stringify(payload)
    }
);

const data = await resp.json();
console.log(data);

Steps (By Shipment Details)

Retrieve Applicable Contracts by Shipment Details

Find, lookup, or retrieve applicable contracts based on shipment details (i.e., addresses, dates, weights, equipment needed, transportation mode, etc.) using POST /v2/contracts/applicable-contracts (see API reference) and passing in the details of the shipment.

Tip

A core use case of "request_type": "BY_VALUE" is for exploratory contract lookups where there is not an actual shipment with details that the API caller wants to explore the potential matching contracts for yet.

Example request (BY_VALUE)

curlpythonjavajavascript

Copy

Copied

curl -X POST \
  https://sandbox-api.shipwell.com/contracts/applicable-contracts \
  -H 'Authorization: Token YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "currency": "USD",
  "equipment_type": "REEFER",
  "mode": "FTL",
  "stop_addresses": [
    {
      "address_1": "1600 Pennsylvania Ave NW",
      "address_2": null,
      "city": "Washington",
      "state_province": "DC",
      "postal_code": "20500",
      "country": "US",
      "phone_number": "+15555555555",
      "latitude": 38.8977,
      "longitude": -77.0365,
      "timezone": "America/New_York",
      "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US"
    },
    {
      "address_1": "1000 5th Ave",
      "address_2": null,
      "city": "New York",
      "state_province": "NY",
      "postal_code": "10028",
      "country": "US",
      "phone_number": "+12127710500",
      "latitude": 40.7794,
      "longitude": -73.9632,
      "timezone": "America/New_York",
      "formatted_address": "1000 5th Ave, New York, NY 10028, US"
    }
  ],
  "request_type": "BY_VALUE",
  "total_packages": 3,
  "total_weight": 24000,
  "total_weight_unit": "LB"
}
'

Copy

Copied

import requests

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = f"https://{host}{base_path}/contracts/applicable-contracts"

headers = {
    "Authorization": "Token YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
}

data = {
    "currency": "USD",
    "equipment_type": "REEFER",
    "mode": "FTL",
    "stop_addresses": [
        {
            "address_1": "1600 Pennsylvania Ave NW",
            "address_2": None,
            "city": "Washington",
            "state_province": "DC",
            "postal_code": "20500",
            "country": "US",
            "phone_number": "+15555555555",
            "latitude": 38.8977,
            "longitude": -77.0365,
            "timezone": "America/New_York",
            "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US",
        },
        {
            "address_1": "1000 5th Ave",
            "address_2": None,
            "city": "New York",
            "state_province": "NY",
            "postal_code": "10028",
            "country": "US",
            "phone_number": "+12127710500",
            "latitude": 40.7794,
            "longitude": -73.9632,
            "timezone": "America/New_York",
            "formatted_address": "1000 5th Ave, New York, NY 10028, US",
        },
    ],
    "request_type": "BY_VALUE",
    "total_packages": 3,
    "total_weight": 24000,
    "total_weight_unit": "LB",
}

response = requests.post(target_url, headers=headers, json=data)
print(response.json())

Copy

Copied

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.RequestBody;
import okhttp3.MediaType;

OkHttpClient client = new OkHttpClient();

// Configuration
String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/contracts/applicable-contracts";

String requestBody = """
   {
     "currency": "USD",
     "equipment_type": "REEFER",
     "mode": "FTL",
     "stop_addresses": [
       {
         "address_1": "1600 Pennsylvania Ave NW",
         "address_2": null,
         "city": "Washington",
         "state_province": "DC",
         "postal_code": "20500",
         "country": "US",
         "phone_number": "+15555555555",
         "latitude": 38.8977,
         "longitude": -77.0365,
         "timezone": "America/New_York",
         "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US"
       },
       {
         "address_1": "1000 5th Ave",
         "address_2": null,
         "city": "New York",
         "state_province": "NY",
         "postal_code": "10028",
         "country": "US",
         "phone_number": "+12127710500",
         "latitude": 40.7794,
         "longitude": -73.9632,
         "timezone": "America/New_York",
         "formatted_address": "1000 5th Ave, New York, NY 10028, US"
       }
     ],
     "request_type": "BY_VALUE",
     "total_packages": 3,
     "total_weight": 24000,
     "total_weight_unit": "LB"
   }
   """;

// Build and execute the request
Request request = new Request.Builder()
    .url(targetUrl)
    .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
    .header("Authorization", "Token YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .build();

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) {
        throw new IOException("Unexpected code " + response);
    }
    System.out.println(response.body().string());
}

Copy

Copied

const payload = {
    "currency": "USD",
    "equipment_type": "REEFER",
    "mode": "FTL",
    "stop_addresses": [{
            "address_1": "1600 Pennsylvania Ave NW",
            "address_2": null,
            "city": "Washington",
            "state_province": "DC",
            "postal_code": "20500",
            "country": "US",
            "phone_number": "+15555555555",
            "latitude": 38.8977,
            "longitude": -77.0365,
            "timezone": "America/New_York",
            "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US"
        },
        {
            "address_1": "1000 5th Ave",
            "address_2": null,
            "city": "New York",
            "state_province": "NY",
            "postal_code": "10028",
            "country": "US",
            "phone_number": "+12127710500",
            "latitude": 40.7794,
            "longitude": -73.9632,
            "timezone": "America/New_York",
            "formatted_address": "1000 5th Ave, New York, NY 10028, US"
        }
    ],
    "request_type": "BY_VALUE",
    "total_packages": 3,
    "total_weight": 24000,
    "total_weight_unit": "LB"
};

const basePath = "/v2";
const host = "sandbox-api.shipwell.com"
const targetUrl = `https://${host}${basePath}/contracts/applicable-contracts`;

const resp = await fetch(
    targetUrl, {
        method: "POST",
        headers: {
            "Authorization": "Token YOUR_ACCESS_TOKEN",
            "Content-Type": "application/json"
        },
        body: JSON.stringify(payload)
    }
);

const data = await resp.json();
console.log(data);

Retrieve Applicable Contracts Response

Note

The API response for retrieving applicable contracts BY_SHIPMENT (shipment_id) or BY_VALUE (shipment details) is the same object / object shape. See the applicable contracts response schema here.

Example response

The response returns a HTTP 200 (OK) status code for success in the response headers.

Copy

Copied

{
   "data":[
      {
         "contract":{
            "id":"1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
            "name":"White House to Met Museum",
            "carrier_relationship":"d7f1b7aa-c04c-4a8f-9449-6b6fba2e6ed0",
            "carrier_name":"Swift Transportation",
            "status":"ACTIVE",
            "start_date":"2025-06-01",
            "end_date":"2026-06-01",
            "external_id":"WH-MET-2025",
            "notes":"Premium service contract for high-value art transport",
            "origins":[
               {
                  "id":"origin-1",
                  "address_1":"1600 Pennsylvania Ave NW",
                  "address_2":"",
                  "city":"Washington",
                  "state_province":"DC",
                  "postal_code":"20500",
                  "country":"US",
                  "phone_number":"+5555555555",
                  "latitude":38.8977,
                  "longitude":-77.0365,
                  "timezone":"America/New_York",
                  "formatted_address":"1600 Pennsylvania Ave NW, Washington, DC 20500, US",
                  "created_at":"2025-06-27T17:52:29Z",
                  "updated_at":"2025-06-27T17:52:29Z"
               }
            ],
            "destinations":[
               {
                  "id":"destination-1",
                  "address_1":"1000 5th Ave",
                  "address_2":"",
                  "city":"New York",
                  "state_province":"NY",
                  "postal_code":"10028",
                  "country":"US",
                  "phone_number":"+5555555555",
                  "latitude":40.7794,
                  "longitude":-73.9632,
                  "timezone":"America/New_York",
                  "formatted_address":"1000 5th Ave, New York, NY 10028, USA",
                  "created_at":"2025-06-27T17:52:29Z",
                  "updated_at":"2025-06-27T17:52:29Z"
               }
            ],
            "additional_stops":[
               {
                  "id":"additional-stop-1",
                  "address_1":"1 Market St",
                  "address_2":"",
                  "city":"San Francisco",
                  "state_province":"CA",
                  "postal_code":"94105",
                  "country":"US",
                  "phone_number":"+14155550123",
                  "latitude":37.7903,
                  "longitude":-122.3906,
                  "timezone":"America/Los_Angeles",
                  "order_index":1,
                  "additional_stop_charge":150.00,
                  "additional_stop_charge_currency":"USD",
                  "created_at":"2025-06-27T17:52:29Z",
                  "updated_at":"2025-06-27T17:52:29Z"
               }
            ],
            "equipment_types":[
               {
                  "id":1,
                  "machine_readable":"DRY_VAN",
                  "name":"Dry Van"
               }
            ],
            "modes":[
               {
                  "code":"FTL",
                  "description":"Full Truckload",
                  "id":1
               }
            ],
            "default_accessorials":[
               {
                  "charge_code":"LHS",
                  "amount":20.00,
                  "currency":"USD",
                  "description":"Loading Helper Service",
                  "type":"pickup"
               },
               {
                  "charge_code":"UHS",
                  "amount":20.00,
                  "currency":"USD",
                  "description":"Unloading Helper Service",
                  "type":"delivery"
               }
            ],
            "documents":[
               {
                  "id":"497f6eca-6276-4993-bfeb-53cbbbba6f08",
                  "file_url":"https://example.com/contracts/WH-MET-2025.pdf",
                  "type":"CONTRACT",
                  "filename":"WH-MET-2025_Contract.pdf",
                  "description":"Contract agreement for White House to Met Museum transport",
                  "created_at":"2025-06-27T17:52:29Z"
               }
            ],
            "rate_table":{
               "base_rate":1.50,
               "currency":"USD",
               "rate_type":"PER_MILE",
               "minimum_rate":100.00,
               "distance_unit":"MILE",
               "package_type":"PALLET",
               "rate_bands":[
                  {
                     "range_start":"0",
                     "range_end":"500",
                     "rate":"1.50",
                     "rate_application_type":"RATE_PER_UNIT",
                     "rate_assessment_measurement":"DISTANCE",
                     "freight_class_rates":[
                        {
                           "freight_class":"50",
                           "rate":"1.50"
                        }
                     ]
                  }
               ]
            },
            "created_at":"2025-06-27T17:52:29Z",
            "updated_at":"2025-06-27T17:52:29Z"
         },
         "contract_lane":{
            "id":"0f81019f-236c-486a-9f3b-4e8c45d12345",
            "origin":{
               "id":"origin-1",
               "address_1":"1600 Pennsylvania Ave NW",
               "address_2":"",
               "city":"Washington",
               "state_province":"DC",
               "postal_code":"20500",
               "country":"US",
               "phone_number":"+12024561414",
               "latitude":38.8977,
               "longitude":-77.0365,
               "timezone":"America/New_York",
               "formatted_address":"1600 Pennsylvania Ave NW, Washington, DC 20500, USA",
               "created_at":"2025-06-27T17:52:29Z",
               "updated_at":"2025-06-27T17:52:29Z"
            },
            "destination":{
               "id":"destination-1",
               "address_1":"1000 5th Ave",
               "address_2":"",
               "city":"New York",
               "state_province":"NY",
               "postal_code":"10028",
               "country":"US",
               "phone_number":"+12127710500",
               "latitude":40.7794,
               "longitude":-73.9632,
               "timezone":"America/New_York",
               "formatted_address":"1000 5th Ave, New York, NY 10028, USA",
               "created_at":"2025-06-27T17:52:29Z",
               "updated_at":"2025-06-27T17:52:29Z"
            },
            "equipment_types":[
               {
                  "id":1,
                  "machine_readable":"DRY_VAN",
                  "name":"Dry Van"
               }
            ],
            "modes":[
               "FTL"
            ],
            "rate_info":{
               "id":"5a6b7c8d-9e0f-1g2h-3i4j-5k6l7m8n9o0p",
               "created_at":"2025-06-27T17:52:29Z",
               "updated_at":"2025-06-27T17:52:29Z",
               "rate_bands":[
                  {
                     "range_start":"0",
                     "range_end":"500",
                     "rate":"1.50",
                     "rate_application_type":"RATE_PER_UNIT",
                     "rate_assessment_measurement":"DISTANCE",
                     "freight_class_rates":[
                        {
                           "freight_class":"50",
                           "rate":"1.50"
                        }
                     ]
                  }
               ],
               "band_calculation_measurement":"DISTANCE",
               "rate_assessment_measurement":"DISTANCE",
               "package_type":"PALLET",
               "distance":500.00,
               "distance_unit":"MILE",
               "minimum_rate":100.00,
               "rate":1.50,
               "rate_type":"PER_MILE",
               "weight_unit":"LB"
            }
         }
      }
   ]
}