Skip to main content

Bol And Drop V1 Ep

POST 
/v1/bols_and_drops

Fetch Order Details

Fetches details about orders, including Bills of Lading (BOLs), drop details, and associated costs based on a set of filtering criteria. Essential for logistics and supply chain operations, offering insights into order movements, statuses, and financial implications.

Required Scopes (io.r)

Request​

order_date_start: datetime | None = None
The start date for filtering orders based on their order date.

order_date_end: datetime | None = None
The end date for filtering orders based on their order date.

movement_updated_start: datetime | None = None
The start date for filtering orders based on their last movement update.

movement_updated_end: datetime | None = None
The end date for filtering orders based on their last movement update.

last_change_date: datetime | None = None
The last change date of the order. Types of changes that will update this date:

  • Drop / BOL added or edited
  • Order modified (location, supply, etc.)
  • Order Creation
  • Order Completion
  • Order Assignment Change (Driver, Carrier, etc.)

order_ids: list[str] = []
A list of order IDs to specifically include in the search.

order_numbers: list[int] = []
A list of order numbers to specifically include in the search.

order_states: list[OrderState] = []
A list of order states to filter the orders. Includes states like 'open', 'complete', and 'canceled'.

Order State

Canceled
A user canceled the order.

Deleted
A user deleted the order.

Open
Created orders that are not yet assigned. The default.

Recommended
Depricated.

Accepted
The state of a carrier assigned order once a carrier accepts the order assigned to them.

Assigned
A driver is assigned to an order.

In Progress
A driver is currently working on the order.

order_types: list[OrderType] = []
A list of order types to filter the orders. Types include 'backhaul' and 'regular'.

include_invalid: bool = False
A flag to include orders that have been marked as invalid in the results.

include_bol_allocation: bool = False
a flag to include allocated_bols

reference_order_number: list[str] | None = []
A list of external order number attached to the order to be used as a reference for an outside system.


Response​

The response includes a collection of orders with their associated BOLs, drops, and costs:

order_number: int
The number associated with the order.

order_id: str
The unique identifier of the order.

po: str
The purchase order number related to the order.

carrier: str
The name of the carrier used for the order.

carrier_id: str
The unique identifier of the carrier used for the order.

manager: str
The unique identifier of the inventory managed carrier used for the order.

manager_id: str
The unique identifier of the inventory managed carrier used for the order.

last_movement_update: datetime
The date and time of the last update to the order's movement.

order_date: datetime
The date the order was placed.

status: OrderState
The current status of the order.

Order State

Canceled
A user canceled the order.

Deleted
A user deleted the order.

Open
Created orders that are not yet assigned. The default.

Recommended
Depricated.

Accepted
The state of a carrier assigned order once a carrier accepts the order assigned to them.

Assigned
A driver is assigned to an order.

In Progress
A driver is currently working on the order.

type: OrderType
The type of the order, such as 'regular' or 'backhaul'.

drops: list[DropDetail]
A list of drop details associated with the order.

Show Child Attributes

compartment_indexes: list[int] = None
List of compartment indexes for the drop.

before_stick_inches: int | None = None
The stick inches measured before the drop.

before_stick_time: datetime | None = None
Timestamp when the before drop measurement was taken.

after_stick_inches: int | None = None
The stick inches measured after the drop.

after_stick_time: datetime | None = None
Timestamp when the after drop measurement was taken.

drop_id: str | None = None
Internal identifier for the drop.

location: str | None = None
Name of the location receiving the drop.

location_id: str | None = None
Identifier of the location receiving the drop.

location_source_id: str | None = None
If received from integration, the location identifier inside of the source system.

location_source_system: str | None = None
If received from integration, the name of the source system.

product: str | None = None
Name of the product for the drop.

product_id: str | None = None
Identifier for the product of the drop.

product_source_id: str | None = None
If received from integration, the product identifier inside of the source system.

product_source_system: str | None = None
If received from integration, the name of the source system.

tank_id: int | None = None
Identifier of the tank receiving the drop.

tank_source_id: str | None = None
If received from integration, the tank identifier inside of the source system.

tank_source_system: str | None = None
If received from integration, the name of the source system.

volume: float | None = None
Volume of the drop.

driver_id: str | None = None
Identifier of the driver executing the drop.

driver_username: str | None = None
Username of the driver executing the drop.

driver_extra_data: dict | None = None
Any additional data provided or managed by the client for drivers through integration endpoints.

driver_name: str | None = None
Name of the driver executing the drop.

driver_date: datetime | None = None
Driver's schedule date.

driver_shift: str | None = None
Driver's shift, either AM or PM.

driver_shift_id: str | None = None
Driver's schedule identifier.

tractor_number: str | None = None
Tractor number associated with the driver or drop.

trailer_number: str | None = None
Trailer number associated with the driver or drop.

blend_codes: list[str] = []
List of blend codes associated with the drop product, if applicable.

site_counterparty_id: str | None = None
The counterparty identifier for the site.

site_counterparty_name: str | None = None
The counterparty name for the site.

freight_customer_id: str | None = None
The freight customer identifier for the site.

freight_customer_name: str | None = None
The freight customer name for the site.

bols: list[BOLDetail]
A list of BOL details associated with the order.

Show Child Attributes

bol_number: str | None = None
Number associated with the BOL.

bol_id: str | None = None
Internal identifier for the BOL.

date: datetime | None = None
Date of BOL.

details: list[BolDetailResponse] = None
List containing detailed information for each compartment in the BOL.

Show Child Attributes

compartment_index: int | None = None
Compartment associated with BOL detail.

load_number: str | None = None
Load number associated with the BOL detail.

product: str | None = None
BOL detail product name.

product_id: str | None = None
BOL detail product identifier.

product_source_id: str | None = None
If received from integration, the product identifier inside of the source system.

product_source_system: str | None = None
If received from integration, the product source system name.

net_volume: float | None = None
Net volume of product in the compartment.

gross_volume: float | None = None
Gross volume of product in the compartment.

supplier: str | None = None
The counterparty name of the supplier for the BOL Detail product.

supplier_id: str | None = None
The counterparty identifier of the supplier for the BOL Detail product.

supplier_source_id: str | None = None
If received from integration, the supplier identifier inside of the source system.

supplier_source_system: str | None = None
If received from integration, the supplier source system name.

contract: str | None = None
Contract name associated with the BOL detail.

price_details: BOLPrice | None = None
Bol price details.

Show Child Attributes

price: float | None = None
BOL price amount.

price_id: str | None = None
The price identifier of the BOL price.

curve_id: str | None = None
A price curve identifier to associate with the request.

date: datetime | None = None
Date of the bol price.

counterparty_id: str | None = None
The counterparty identifier of the supplier the price.

load_or_drop: str | None = None
Identifies whether the BOL is for a load or drop.

location: str | None = None
Location name associated with the BOL.

location_id: str | None = None
Location identifier associated with the BOL.

location_source_id: str | None = None
If received from integration, the location identifier inside of the source system.

location_source_system: str | None = None
If received from integration, the location source system name.

driver_id: str | None = None
Identifier of the driver in charge of the load or drop for this BOL.

driver_username: str | None = None
Username of the driver in charge of the load or drop for this BOL.

driver_extra_data: dict | None = None
Any additional data provided or managed by the client for drivers through integration endpoints.

driver_name: str | None = None
Name of the driver in charge of the load or drop for this BOL.

driver_date: datetime | None = None
Driver shift date.

driver_shift: str | None = None
Shift the driver was on for this BOL — Can be either AM or PM.

driver_shift_id: str | None = None
Driver schedule identifier associated with this BOL.

tractor_number: str | None = None
Driver tractor number specific to this BOL.

trailer_number: str | None = None
Driver trailer number specific to this BOL.

costs: list[FreightCostDetail]
A list of freight cost details associated with the order.

Show Child Attributes

cost_type: str | None = None
Always set to "freight".

carrier: str | None = None
Name of the carrier counterparty involved in the freight.

carrier_source_id: str | None = None
If received from integration, the identifier of the carrier within the source system.

carrier_source_system: str | None = None
If received from integration, the name of the carrier's source system.

per_unit_price: float | None = None
Unit cost of the freight as gathered from the supply option.

cost_amount: float | None = None
Total cost of the freight as calculated from the supply option.

validation_bypass_on: datetime | None
The date and time when validation was bypassed for the order, if applicable.

has_additives: bool | None = False
Indicates whether the order includes additives.

allocated_bol_error: str | None = None
After the system attempts to allocate BOLs it runs an extra set of validations to check the validity of the volumes. If the allocation process failed or the validation failed, this field will contain an error.

allocated_bol_issue: str | None = None
See allocated_bol_error field for more info. If the allocation process failed or the validation failed a heuristic will run to try an detect the problem with the order. If a known issue is found a more useful message will be placed here.

allocated_bols: list[AllocatedBolResponse] | None = False
a list of allocated BOLs included if include_allocated_bols is set to true in request

estimated_freight: Freight | None = []
Estimated freight items.

Show Child Attributes

root: List[FreightItem] | None = []
List of freight items.

Show Child Attributes

id: str | None = None
Identifier of the freight item.

rate: float
The rate for the freight item.

quantity: float
The amount of the freight item according to the unit.

unit: str
Unit of measure for the freight item.

type: FreightType
Types of freight items.

Types

Freight Rate

Accessorial

Surcharge

Point to Point

Undefined

sub_type: str | None = None
Unit of measure for the freight item.

product_group: str | None = None
Type of product. Gasoline or Diesel.

legs: str | None = None
List of freight leg information.

Show Child Attributes

origin: str
Name of the origin location of the freight leg.

origin_id: str
Identifier of the origin location of the freight leg.

destination: str
Name of the destination location of the freight leg.

destination_id: str
Identifier of the destination location of the freight leg.

distance: float
Total miles for the leg.

manual: boolean | None = False
Indicates if freight is manual.

use_surcharge: boolean | None = None
Indicates if freight item uses surgcharges.

total: float | None = None
Rate times quantity.

last_change_date: datetime | None = None
The last change date of the order. Types of changes that will update this date:

  • Drop / BOL added or edited
  • Order modified (location, supply, etc.)
  • Order Creation
  • Order Completion
  • Order Assignment Change (Driver, Carrier, etc.)

reference_order_number: str | None = None
External order number attached to the order to be used as a reference for an outside system.

Responses​

Successful Response

[
  {
    "order_number": "string",
    "order_id": "string",
    "po": "string",
    "carrier": "string",
    "carrier_id": "string",
    "manager": "string",
    "manager_id": "string",
    "last_movement_update": "2025-12-17T21:49:50.643Z",
    "order_date": "2025-12-17T21:49:50.643Z",
    "status": "string",
    "type": "string",
    "drops": [
      {
        "compartment_indexes": [
          0
        ],
        "before_stick_inches": 0,
        "before_stick_time": "2025-12-17T21:49:50.643Z",
        "after_stick_inches": 0,
        "after_stick_time": "2025-12-17T21:49:50.643Z",
        "drop_id": "string",
        "location": "string",
        "location_id": "string",
        "location_source_id": "string",
        "location_source_system": "string",
        "product": "string",
        "product_id": "string",
        "product_source_id": "string",
        "product_source_system": "string",
        "tank_id": 0,
        "tank_source_id": "string",
        "tank_source_system": "string",
        "volume": 0,
        "driver_id": "string",
        "driver_username": "string",
        "driver_extra_data": {},
        "driver_name": "string",
        "driver_date": "2025-12-17T21:49:50.643Z",
        "driver_shift": "string",
        "driver_shift_id": "string",
        "tractor_number": "string",
        "trailer_number": "string",
        "blend_codes": [
          "string"
        ],
        "site_counterparty_id": "string",
        "site_counterparty_name": "string",
        "freight_customer_id": "string",
        "freight_customer_name": "string"
      }
    ],
    "bols": [
      {
        "bol_number": "string",
        "bol_id": "string",
        "date": "2025-12-17T21:49:50.643Z",
        "details": [
          {
            "compartment_index": 0,
            "load_number": "string",
            "product": "string",
            "product_id": "string",
            "product_source_id": "string",
            "product_source_system": "string",
            "net_volume": 0,
            "gross_volume": 0,
            "supplier": "string",
            "supplier_id": "string",
            "supplier_source_id": "string",
            "supplier_source_system": "string",
            "contract": "string",
            "price_details": {
              "price": 0,
              "price_id": "string",
              "curve_id": "string",
              "date": "2025-12-17T21:49:50.643Z",
              "counterparty_id": "string"
            }
          }
        ],
        "load_or_drop": "string",
        "location": "string",
        "location_id": "string",
        "location_source_id": "string",
        "location_source_system": "string",
        "driver_id": "string",
        "driver_username": "string",
        "driver_extra_data": {},
        "driver_name": "string",
        "driver_date": "2025-12-17T21:49:50.643Z",
        "driver_shift": "string",
        "driver_shift_id": "string",
        "tractor_number": "string",
        "trailer_number": "string"
      }
    ],
    "costs": [
      {
        "cost_type": "string",
        "carrier": "string",
        "carrier_source_id": "string",
        "carrier_source_system": "string",
        "per_unit_price": 0,
        "cost_amount": 0
      }
    ],
    "validation_bypass_on": "2025-12-17T21:49:50.643Z",
    "has_additives": true,
    "estimated_freight": {
      "id": "string",
      "parent": "string",
      "created_at": "2025-12-17T21:49:50.643Z",
      "type": "freight",
      "status": "open",
      "reversed": false,
      "transactions": [
        {
          "model_type": "base",
          "type": "Base Freight",
          "subtype": "string",
          "rate": 0,
          "amount": 0,
          "total": 0,
          "uom": "string",
          "errors": [
            "string"
          ],
          "id": "string",
          "product_group": "string",
          "product_id": "string",
          "product_name": "string",
          "origin": "string",
          "origin_id": "string",
          "origin_override": "string",
          "origin_id_override": "string",
          "destination": "string",
          "destination_id": "string",
          "destination_override": "string",
          "destination_id_override": "string",
          "legs": [
            {
              "origin": "string",
              "origin_id": "string",
              "destination": "string",
              "destination_id": "string",
              "distance": 0
            }
          ],
          "use_surcharge": true,
          "manual": false,
          "has_dependency": false,
          "created_date": "2025-12-17T21:49:50.643Z",
          "requires_approval": false,
          "requires_approval_reason_code": false,
          "is_approved": false,
          "approved_by": "string",
          "approved_date": "2025-12-17T21:49:50.643Z",
          "approved_reason_code": "string",
          "amount_override": 0,
          "rate_override": 0,
          "product_id_override": "string",
          "product_name_override": "string",
          "product_group_override": "string",
          "subtype_override": "string",
          "uom_override": "string",
          "total_override": 0,
          "override_by": "string",
          "override_date": "2025-12-17T21:49:50.643Z",
          "exclude_from_invoice": false,
          "credit_rebill_metadata": {
            "impact_type": "impacted",
            "delta_amount": 0,
            "delta_base_total": 0,
            "delta_surcharge_total": 0,
            "delta_accessorial_total": 0,
            "delta_total": 0
          },
          "extra_data": {},
          "gross_volume": 0,
          "net_volume": 0,
          "bol_date": "2025-12-17T21:49:50.643Z",
          "bol_number": "string",
          "bol_number_override": "string",
          "delivery_date": "2025-12-17T21:49:50.643Z"
        }
      ],
      "counterparty_id": "string",
      "book_type": "Cost",
      "effective_date_used": "2025-12-17T21:49:50.643Z",
      "invoice_group_id": "string",
      "invoice_number": "string",
      "accessorial_invoice_number": "string",
      "new_version_available": false,
      "new_version_total": 0,
      "error": {
        "type": "No Freight Rate",
        "message": "string"
      }
    },
    "actual_freight": {
      "id": "string",
      "parent": "string",
      "created_at": "2025-12-17T21:49:50.644Z",
      "type": "freight",
      "status": "open",
      "reversed": false,
      "transactions": [
        {
          "model_type": "base",
          "type": "Base Freight",
          "subtype": "string",
          "rate": 0,
          "amount": 0,
          "total": 0,
          "uom": "string",
          "errors": [
            "string"
          ],
          "id": "string",
          "product_group": "string",
          "product_id": "string",
          "product_name": "string",
          "origin": "string",
          "origin_id": "string",
          "origin_override": "string",
          "origin_id_override": "string",
          "destination": "string",
          "destination_id": "string",
          "destination_override": "string",
          "destination_id_override": "string",
          "legs": [
            {
              "origin": "string",
              "origin_id": "string",
              "destination": "string",
              "destination_id": "string",
              "distance": 0
            }
          ],
          "use_surcharge": true,
          "manual": false,
          "has_dependency": false,
          "created_date": "2025-12-17T21:49:50.644Z",
          "requires_approval": false,
          "requires_approval_reason_code": false,
          "is_approved": false,
          "approved_by": "string",
          "approved_date": "2025-12-17T21:49:50.644Z",
          "approved_reason_code": "string",
          "amount_override": 0,
          "rate_override": 0,
          "product_id_override": "string",
          "product_name_override": "string",
          "product_group_override": "string",
          "subtype_override": "string",
          "uom_override": "string",
          "total_override": 0,
          "override_by": "string",
          "override_date": "2025-12-17T21:49:50.644Z",
          "exclude_from_invoice": false,
          "credit_rebill_metadata": {
            "impact_type": "impacted",
            "delta_amount": 0,
            "delta_base_total": 0,
            "delta_surcharge_total": 0,
            "delta_accessorial_total": 0,
            "delta_total": 0
          },
          "extra_data": {},
          "gross_volume": 0,
          "net_volume": 0,
          "bol_date": "2025-12-17T21:49:50.644Z",
          "bol_number": "string",
          "bol_number_override": "string",
          "delivery_date": "2025-12-17T21:49:50.644Z"
        }
      ],
      "counterparty_id": "string",
      "book_type": "Cost",
      "effective_date_used": "2025-12-17T21:49:50.644Z",
      "invoice_group_id": "string",
      "invoice_number": "string",
      "accessorial_invoice_number": "string",
      "new_version_available": false,
      "new_version_total": 0,
      "error": {
        "type": "No Freight Rate",
        "message": "string"
      }
    },
    "allocated_bol_error": "string",
    "allocated_bol_issue": "string",
    "allocated_bols": [
      {
        "bol_number": "string",
        "bol_id": "string",
        "bol_terminal_id": "string",
        "bol_terminal": "string",
        "bol_product": "string",
        "bol_product_id": "string",
        "bol_supplier": "string",
        "bol_supplier_id": "string",
        "bol_net_volume_original": 0,
        "bol_gross_volume_original": 0,
        "store_number": "string",
        "store_id": "string",
        "location_id": "string",
        "store_tank": 0,
        "store_product": "string",
        "store_product_id": "string",
        "store_timezone": "string",
        "bol_net_volume_allocated": 0,
        "bol_gross_volume_allocated": 0,
        "driver_schedule": "string",
        "bol_date": "2025-12-17T21:49:50.644Z",
        "delivered_date": "2025-12-17T21:49:50.644Z",
        "price": {
          "contract": "string",
          "price_type": "string",
          "price_id": "string",
          "curve_id": "string",
          "price": 0,
          "date": "2025-12-17T21:49:50.644Z",
          "expired": true
        }
      }
    ],
    "last_change_date": "2025-12-17T21:49:50.644Z",
    "reference_order_number": "string"
  }
]
Loading...