Calculate Charge Items for a Shipment Under A Specific Contract

Overview

Learn the best practices on how to calculate charge items in the Shipwell API. We'll cover calculating charge items for a specific contract using POST /v2/contracts/{contractId}/calculate-charge-items (see API reference).

In logistics and shipping, charge items are the individual line‐level fees that make up the total cost of moving a shipment. Think of them as the building blocks of your invoice: you'll typically see a base transportation rate plus any number of additional charge items like fuel surcharges, residential delivery fees, lift‐gate services, customs duties, and so on all broken out as separate items. Each charge item includes a unique code or identifier (charge_code), a human‐readable description/name (unit_name), the currency (unit_amount_currency), and the monetary amount (amount or if broken down by unit and quantity then unit_amount). Some charges are distance-based and include distance_unit (e.g., MILE, KILOMETER) and total_distance (e.g. 123.45).

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)

Calculate Charge Items by Shipment Id

Calculate detailed charge items for a specific contract based on the shipment identifier (aka shipment_id) using POST /v2/contracts/{contractId}/calculate-charge-items (see API reference) and passing in the details of the shipment (i.e., addresses, weights, etc.).

Tip

The body or payload of the POST /v2/contracts/{contractId}/calculate-charge-items request has a request_type property that determines if the charge items are calculated 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/contracts/{contractId}/calculate-charge-items \
  -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

contract_id = "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p";
shipment_id = "b2888076-051c-46f7-bd75-c96720f94a9e"

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = f"https://{host}{base_path}/contracts/{contract_id}/calculate-charge-items"

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 contractId = "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p";
String shipmentId = "b2888076-051c-46f7-bd75-c96720f94a9e";

String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  basePath +
  "/contracts/" + contractId + "/calculate-charge-items";

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 contractId = "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p";
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/${contractId}/calculate-charge-items`;

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)

Calculate Charge Items by Shipment Details

Calculate detailed charge items for a specific contract based on shipment details (i.e., addresses, dates, weights, equipment needed, transportation mode, etc.) using POST /v2/contracts/{contractId}/calculate-charge-items (see API reference) and passing in the details of the shipment.

Tip

A core use case of "request_type": "BY_VALUE" is for exploratory charge item calculation where there is not an actual shipment with details that the API caller wants to explore the potential charges and costs associated with a particular set of shipment data if a specific contract is applied or used.

Example request (BY_VALUE)

curlpythonjavajavascript

Copy

Copied

curl -X POST \
  https://sandbox-api.shipwell.com/contracts/{contractId}/calculate-charge-items \
  -H 'Authorization: Token YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "request_type": "BY_VALUE",
    "currency": "USD",
    "equipment_type": "TRUCK",
    "mode": "LTL",
    "planned_date": "2025-10-18",
    "stop_addresses": [
      {
        "address_1": "1600 Pennsylvania Ave NW",
        "city": "Washington",
        "state_province": "DC",
        "country": "US",
        "latitude": 38.8977,
        "longitude": -77.0365,
        "postal_code": "20500",
        "phone_number":"+5555555555",
        "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US"
      },
      {
        "address_1": "1000 5th Ave",
        "city": "New York",
        "state_province": "NY",
        "country": "US",
        "latitude": 40.7794,
        "longitude": -73.9632,
        "postal_code": "10028",
        "phone_number":"+5555555555",
        "formatted_address": "1000 5th Ave, New York, NY 10028, US"
      }
    ],
    "total_packages": 1,
    "total_weight": 1000.25,
    "total_weight_unit": "LB"
}'

Copy

Copied

import requests

contract_id = "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = f"https://{host}{base_path}/contracts/{contract_id}/calculate-charge-items"

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

data = {
    "request_type": "BY_VALUE",
    "currency": "USD",
    "equipment_type": "TRUCK",
    "mode": "LTL",
    "planned_date": "2025-10-18",
    "stop_addresses": [
        {
            "address_1": "1600 Pennsylvania Ave NW",
            "city": "Washington",
            "state_province": "DC",
            "country": "US",
            "latitude": 38.8977,
            "longitude": -77.0365,
            "postal_code": "20500",
            "phone_number":"+5555555555",
            "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US"
        },
        {
            "address_1": "1000 5th Ave",
            "city": "New York",
            "state_province": "NY",
            "country": "US",
            "latitude": 40.7794,
            "longitude": -73.9632,
            "postal_code": "10028",
            "phone_number":"+5555555555",
            "formatted_address": "1000 5th Ave, New York, NY 10028, US"
        },
    ],
    "total_packages": 1,
    "total_weight": 1000.25,
    "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 contractId = "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p";

String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/contracts/" + contractId + "/calculate-charge-items";

String requestBody = """
    {
        "request_type": "BY_VALUE",
        "currency": "USD",
        "equipment_type": "TRUCK",
        "mode": "LTL",
        "planned_date": "2025-10-18",
        "stop_addresses": [
            {
                "address_1": "1600 Pennsylvania Ave NW",
                "city": "Washington",
                "state_province": "DC",
                "country": "US",
                "latitude": 38.8977,
                "longitude": -77.0365,
                "postal_code": "20500",
                "phone_number":"+5555555555",
                "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US"
            },
            {
                "address_1": "1000 5th Ave",
                "city": "New York",
                "state_province": "NY",
                "country": "US",
                "latitude": 40.7794,
                "longitude": -73.9632,
                "postal_code": "10028",
                "phone_number":"+5555555555",
                "formatted_address": "1000 5th Ave, New York, NY 10028, US"
            }
        ],
        "total_packages": 1,
        "total_weight": 1000.25,
        "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 contractId = "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p";
const payload = {
    "request_type": "BY_VALUE",
    "currency": "USD",
    "equipment_type": "TRUCK",
    "mode": "LTL",
    "planned_date": "2025-10-18",
    "stop_addresses": [
        {
            "address_1": "1600 Pennsylvania Ave NW",
            "city": "Washington",
            "state_province": "DC",
            "country": "US",
            "latitude": 38.8977,
            "longitude": -77.0365,
            "postal_code": "20500",
            "phone_number":"+5555555555",
            "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, US"
        },
        {
            "address_1": "1000 5th Ave",
            "city": "New York",
            "state_province": "NY",
            "country": "US",
            "latitude": 40.7794,
            "longitude": -73.9632,
            "postal_code": "10028",
            "phone_number":"+5555555555",
            "formatted_address": "1000 5th Ave, New York, NY 10028, US",
        },
    ],
    "total_packages": 1,
    "total_weight": 1000.25,
    "total_weight_unit": "LB",
};


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

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);

Calculate Charge Items Response

Note

The API response for calculating charge items BY_SHIPMENT (shipment_id) or BY_VALUE (shipment details) is the same object / object shape.

Example response

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

Copy

Copied

{
  "charges": [
    {
      "amount": 20.00,
      "category": "LH",
      "charge_code": "LHS",
      "distance_unit": null,
      "total_distance": null,
      "unit_amount": 20.00,
      "unit_amount_currency": "USD",
      "unit_name": "Linehaul Service",
      "unit_quantity": 1.0
    },
    {
      "amount": 60.00,
      "category": "FSC",
      "charge_code": "405",
      "distance_unit": null,
      "total_distance": null,
      "unit_amount": 60.00,
      "unit_amount_currency": "USD",
      "unit_name": "Fuel Surcharge",
      "unit_quantity": 1.0
    }
  ]
}