Get Orders V1 Ep
POST/v1/order/get_orders
Get Orders V1 Endpoint - Query Orders and Order Requests with Filters
Retrieves detailed information about orders and order requests based on specified criteria such as order ID, order number, type, state, and the last change date. This endpoint provides a comprehensive view of orders to support various operational needs. Responses limited to 3,500 orders.
Order requests do not have all the fields that an order will have. Until the request is fulfilled it lacks some fields relevant to an actual order.
Request
order_id: str | None = None
Internal order ID. If provided, the endpoint will return only the order with this ID.
order_number: int | None_ = None
Unique number for the order. If provided, the endpoint will return only the order with this number.
type: str | None = None
Order type. Filters orders to include those that match the specified type.
Show Supported Types
Regular
Order where fuel is delivered to a site.
Backhaul
Order where fuel is taken from a destination to another location.
order_request
This is an order request, where an order is subsequently created and fulfilled from a request. This returns only order_requests
state: str | None = None
Order state. Filters orders to include those in the specified state.
Show Supported States
Accepted
Order is awaiting dispatch to a carrier or driver.
Assigned
Order has been dispatched to a driver or a carrier.
In Progress
Order has been started by a driver or a carrier.
Carrier orders are typically ran outside the system and may not show up in this state unless the carrier is integrated.
Complete
Order has been completed.
Canceled
User has canceled the order or order 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.
last_change_date: datetime | None = None
The last change date of the order or order request. 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 Request Creation
- Order Request Assigned
- Order Request Completed
reference_order_number: str | None = None
External order number attached to the order to be used as a reference for an outside system.
order_date: datetime | None = None
The creation date of the order or order request.
carrier_notify_states: list[str] | None = None
Filter orders by carrier notification states. Allows filtering based on the notification status of orders sent to carriers.
Show Supported States
none
No notification has been sent to the carrier.
pending
Notification to carrier is pending.
sent
Notification has been successfully sent to the carrier.
failed
Notification to carrier failed.
accepted
Carrier has accepted the order.
assigned
Order has been assigned to a carrier.
staged
Order is staged for carrier notification.
Response
order_id: str
Internal order identifier.
drivers: list =[]
List of drivers assigned to the order, each containing:
Show Child Attributes
driver_id: str = None
Driver identifier.
driver_schedule_id: str = None
Driver schedule identifier.
name: str = None
Driver's name.
username: str = None
Driver's username.
order_number: str = None
Unique number for the order.
po_number: str = None
PO number for the order.
order_date: datetime = None
The creation date of the order.
last_change_date : datetime = 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 Request Creation
- Order Request Assigned
- Order Request Completed
order_state: str = None
Current state of the order or order request.For ordersw, includes states like 'open', 'complete', and 'canceled'.
for order requests includes 'pending', 'canceled'
Order State
Canceled
A user canceled the order or order request.
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.
Pending
A pending state is for order requests only, the request has not been assigned an order and will need to manually select supply options.
carrier_window_start: datetime | None = None
Start timestamp for when a carrier can deliver the order.
carrier_window_end: datetime | None = None
End timestamp for delivery by a carrier.
carrier_window_start_local: str | None = None
Carrier window start time adjusted to the site's local timezone offset.
carrier_window_end_local: str | None = None
Carrier window end time adjusted to the site's local timezone offset.
carrier_notify_state: str | None = None
State of the order in relation to the carrier.
load_window_start: datetime = None
Beginning of the time period for loading.
load_window_end: datetime = None
End of the time period for loading.
dispatch_window_start: datetime = None
Beginning of the time period for dispatching.
dispatch_window_end: datetime = None
End of the time period for dispatching.
hauler_counterparty_id: str | None = None
Counterparty identifier if hauled by a counterparty.
hauler_counterparty_name: str | None = None
Counterparty name if hauled by a counterparty.
hauler_counterparty_source_id: str | None = None
Hauler counterparty identifier from integration.
hauler_counterparty_source_system: str | None = None
Source system name for the hauler counterparty.
hauled_by_updated_by: str | None = None
User who updated the hauler information.
hauled_by_updated: datetime | None = None
Timestamp of the last update to the hauler information.
loads: list = []
List of loads on the order, each with location details.
Show Child Attributes
location_id: str | None = None
Location identifier of load location.
location_name: str | None = None
Location name of load location.
location_source_id: str | None = None
If received from integration, the identifier inside the source system.
location_source_system: str | None = None
If received from integration, the source system name.
location_type: str | None = None
Load location type. The supported types are Biodiesel Terminal, Ethanol Terminal, Terminal, Depot, Store, and Delivered.
details: list = []
List of each product and specifications connected to a load.
Show Child Attributes
detail_id: str | None = None
Identifier of the drop detail.
counterparty_id: str
Identifier for the counterparty involved in the loads.
counterparty_name: str
Name of the counterparty involved in the loads.
counterparty_source_id: str | None = None
If received from integration, the identifier of the counterparty inside the source system.
counterparty_source_system: str | None = None
If received from integration, the name of the source system.
price_type: str | None = None
Price type of the load. Valid types are "contract", "rack", "index", "inventory", and "spot".
contract: str | None = None
Contract identifier for price used.
product_id: str | None = None
Product identifier for the load detail.
product_name: str | None = None
Product name for the load detail.
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.
drop_product_id: str | None = None
The product identifier related to the dropped product (used for blends).
drop_product_name: str | None = None
The product name related to the dropped product (used for blends).
drop_product_source_id: str | None = None
If received from integration, the identifier of the dropped product inside of the source system.
drop_product_source_system: str | None = None
If received from integration, the name of the source system for the dropped product.
quantity: float | None = None
Amount of the product loaded for this load detail.
compartment_index: int | None = None
The compartment index that the product is loaded into.
blend_code: None | str = None
Blend code, if loading a blended product.
product_codes: list[str] | None = None
List of product codes for the load.
load_number: None | str = None
The load number for the load, if available.
status: str | None_ = None
status of the load can be one of the following:
Show Load Status States
Unset
load state has not been set yet
Driving to Load
driver is enroute to pickup load
Arrived at Load
driver is at location to pickup load
loading
driver is loading
Complete
loading is complete
eta: datetime | None = None
the ETA of the load pickup
drops: list
List of drops on the order, each with location details.
Show Child Attributes
location_id: str | None = None
Location identifier of load location.
location_name: str | None = None
Location name of load location.
location_source_id: str | None = None
If received from integration, the identifier inside the source system.
location_source_system: str | None = None
If received from integration, the source system name.
location_type: str | None = None
Load location type. The supported types are Biodiesel Terminal, Ethanol Terminal, Terminal, Depot, Store, and Delivered.
details: list = []
List of each product and specifications connected to a drop.
Show Child Attributes
detail_id: str | None = None
Identifier of the drop detail.
counterparty_id: str
Identifier for the counterparty involved in the loads.
counterparty_name: str
Name of the counterparty involved in the loads.
counterparty_source_id: str | None = None
If received from integration, the identifier of the counterparty inside the source system.
counterparty_source_system: str | None = None
If received from integration, the name of the source system.
product_id: str | None = None
Product identifier for the load detail.
product_name: str | None = None
Product name for the load detail.
product_source_id: str | None = None
If received from integration, the product identifier inside the source system.
product_source_system: str | None = None
If received from integration, the name of the source system.
quantity: float | None = None
Amount of the product loaded for this load detail.
blend_codes: list[str] | None = None
Terminal specific code for loading a blend.
destination_codes: list[str] | None = None
Site specific codes for the drop.
status: str | None_ = None
status of the drop can be one of the following:
Show Drop Status States
Unset
drop state has not been set yet
Driving to Drop
driver is enroute to pickup drop
Arrived at Drop
driver is dropping
Dropping
driver is dropping
Complete
dropping is complete
eta: datetime | None = None
the ETA of the drop delivery
trip_status: str | None = None
Current trip status of the order.
Trip Status
pre trip
Driver is filling out pre trip form.
preview
Driver is previewing the order.
driving to load
Driver is driving to the load location.
arrived at load
Driver has arrived at the load location.
loading
Driver is loading.
arrived at drop
Driver has arrived at the drop location.
driving to drop
Driver is driving to the drop location.
dropping
Driver is dropping.
heading home
Driver is returning to home depot.
post trip
Driver is filling out post trip form.
complete
Order is complete.
market: str | None = None
Market the order is in.
Supply Option: list | None = None
Supply Information for the order.
Show Child Attributes
option: str | None = ""
Supply option description.
carrier_id: str | None = None
Carrier id for supply option, if delivered.
carrier: str | None = ""
Carrier name for supply option, if delivered.
loaded_miles: float | None = 0
Number of miles for the load.
freight: float | None = 0
Freight amount.
freight_cost: float | None = 0
Total freight cost for the load.
stops: int | None = 0
Number of stops to fulfill the supply.
prices: list = []
List of supply prices.
Show Child Attributes
product_name: str
Product name for supply price.
components: list
List of supply price components
Show Child Attributes
curve_id: str
ID of curve to identify price.
price_id: str
ID of the price.
terminal_id: str
ID of the terminal the price is on.
terminal: str
Terminal name.
supplier_id: str
Supplier for price.
supplier: str
Supplier ID for price.
price_type: str
Price type (list options).
product_id: str
ID of the product.
product: str
Product name.
price: float = 0.0
Price of the product.
contract: str
Contract number/name if price type contract.
volume: float = 0.0
Total volume of the product.
effective_from: datetime
Date the price effective window starts.
effective_to: datetime
Date the price effective window ends.
group_id: str | None = None
Curve group identifier.
group_effective_cutover: datetime | None = None
Date the curve group is effective to.
group_effective_cutover_timezone: str | None = None
Timezone for the effective cutover date.
group_identifier: str | None = None
Curve group identifier.
group_name: str | None = None
Directive group name.
min_constraint: float | None = None
If part of directive, minimum lift constraint.
max_constraint: float | None = None
If part of directive, maximum lift constraint.
load_number: str | None = None
Deprecated. Load number for this supply option.
load_numbers: list[str] | None = []
List of load numbers for the supply option.
product_total: float | None = 0
Total amount of product loaded.
landed_cost: float | None = 0
Total cost including product cost and freight cost.
supply_owner_id: str | None = None
ID of the supplier for the load product.
freight_customer_id: str | None = None
Identifier of the freight customer associated with the site.
delivered: boolean | None = None
If true, order is a delivered order.
out_of_network: bool = False
Signifies whether the supply option is from an in or out of network terminal.
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.
created_by: str | None = None
First and last name of the user that created the order.
note: str | None = None
Order note if any.
estimated_load_minutes: str | None = None
Loaded minutes estimate.
total_miles: str | None = None
Total miles (loaded + unloaded).
loaded_miles: str | None = None
Loaded miles.
unloaded_miles: str | None = None
Unloaded miles (only calculated if on driver schedule).
reference_order_number: str | None = None
External order number attached to the order to be used as a reference for an outside system.
extra_data: dict | None = None
Any additional data provided or managed by the client through integration endpoints.
tractor: str | None = None
tractor used by driver if order in-progress or completed.
trailer: str | None = None
trailer used by driver if order in-progress or completed.
detours: list = []
List of detours associated with the order. Detours represent stops that deviate from the standard load-drop sequence.
Show Child Attributes
id: str
Internal identifier for the detour.
type: str
The type of detour. Currently supported:
no_load
Represents the driver arriving at a terminal but not loading any product.
location_name: str | None = None
Name of the location where the detour occurred.
location_id: str | None = None
Internal identifier of the location where the detour occurred.
date: datetime | None = None
Date and time when the detour occurred.
driver: str | None = None
Name of the driver who performed the detour.
driver_schedule_id: str | None = None
Internal identifier of the driver's schedule associated with the detour.
Responses
- 200
- 422
Successful Response
- application/json
- Example (from schema)
[
{
"type": "regular",
"order_id": "string",
"drivers": [
{
"driver_id": "string",
"driver_schedule_id": "string",
"name": "string",
"username": "string"
}
],
"order_number": 0,
"order_date": "2025-12-17T21:49:50.607Z",
"order_state": "string",
"carrier_window_start": "2025-12-17T21:49:50.607Z",
"carrier_window_end": "2025-12-17T21:49:50.607Z",
"carrier_window_start_local": "string",
"carrier_window_end_local": "string",
"carrier_notify_state": "string",
"load_window_start": "2025-12-17T21:49:50.607Z",
"load_window_end": "2025-12-17T21:49:50.607Z",
"dispatch_window_start": "2025-12-17T21:49:50.607Z",
"dispatch_window_end": "2025-12-17T21:49:50.607Z",
"hauler_counterparty_id": "string",
"hauler_counterparty_name": "string",
"hauler_counterparty_source_id": "string",
"hauler_counterparty_source_system": "string",
"hauled_by_updated_by": "string",
"hauled_by_updated": "2025-12-17T21:49:50.607Z",
"loads": [
{
"location_id": "string",
"location_name": "string",
"location_source_id": "string",
"location_source_system": "string",
"location_type": "string",
"details": [
null
],
"eta": "2025-12-17T21:49:50.607Z",
"status": "string"
}
],
"drops": [
{
"location_id": "string",
"location_name": "string",
"location_source_id": "string",
"location_source_system": "string",
"location_type": "string",
"details": [
null
],
"eta": "2025-12-17T21:49:50.607Z",
"status": "string"
}
],
"detours": [
{
"detour_id": "string",
"type": "no_load",
"location_name": "string",
"location_id": "string",
"completed_at": "2025-12-17T21:49:50.607Z",
"driver": "string",
"driver_schedule_id": "string",
"address": "string",
"city": "string",
"state": "string",
"postal_code": "string"
}
],
"trip_status": "string",
"last_change_date": "2025-12-17T21:49:50.607Z",
"market": "string",
"supply_option": {
"option": "string",
"carrier_id": "string",
"carrier": "string",
"loaded_miles": 0,
"freight": 0,
"freight_cost": 0,
"stops": 0,
"prices": [
{
"product_name": "string",
"volume": 0,
"components": [
{
"timezone_data": {},
"curve_id": "string",
"price_id": "string",
"terminal_id": "string",
"terminal": "string",
"supplier_id": "string",
"supplier": "string",
"price_type": "string",
"product_id": "string",
"product": "string",
"supply_owner_id": "string",
"supply_owner": "string",
"price": 0,
"contract": "string",
"volume": 0,
"effective_from": "2025-12-17T21:49:50.608Z",
"effective_to": "2025-12-17T21:49:50.608Z",
"group_id": "string",
"group_effective_cutover": "2025-12-17T21:49:50.608Z",
"group_effective_cutover_timezone": "string",
"group_identifier": "string",
"group_name": "string",
"min_constraint": 0,
"max_constraint": 0,
"load_number": "string",
"load_numbers": [
"string"
],
"directive_info": {
"curve_group_id": "string",
"directive_name": "string",
"supplier_name": "string",
"projected_load_date": "2025-12-17T21:49:50.608Z",
"total": 0,
"loaded": 0,
"scheduled": 0,
"planned": 0,
"carrier": 0,
"directive_min": 0,
"directive_max": 0,
"alert": true,
"total_excludes_planned": true
}
}
],
"product_total": 0,
"blend_code": "string"
}
],
"product_total": 0,
"landed_cost": 0,
"supply_owner_map": {
"definitions": [
{
"location_name": "string",
"product": "string",
"supply_owner_id": "string"
}
]
},
"freight_customer_id": "string",
"delivered": true,
"out_of_network": false,
"estimated_freight": {
"id": "string",
"parent": "string",
"created_at": "2025-12-17T21:49:50.608Z",
"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.608Z",
"requires_approval": false,
"requires_approval_reason_code": false,
"is_approved": false,
"approved_by": "string",
"approved_date": "2025-12-17T21:49:50.608Z",
"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.608Z",
"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.608Z",
"bol_number": "string",
"bol_number_override": "string",
"delivery_date": "2025-12-17T21:49:50.608Z"
}
],
"counterparty_id": "string",
"book_type": "Cost",
"effective_date_used": "2025-12-17T21:49:50.608Z",
"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"
}
},
"legs": [
{
"origin": "string",
"origin_id": "string",
"destination": "string",
"destination_id": "string",
"distance": 0
}
],
"freight_distance": 0,
"supply_owner_id": "string"
},
"created_by": "string",
"note": "string",
"estimated_load_minutes": 0,
"total_miles": 0,
"loaded_miles": 0,
"unloaded_miles": 0,
"reference_order_number": "string",
"extra_data": {},
"tractor": "string",
"trailer": "string",
"po_number": "string"
},
{
"type": "string",
"number": 0,
"order_id": "string",
"order_number": 0,
"order_date": "2025-12-17T21:49:50.609Z",
"order_state": "Pending",
"reference_order_number": "string",
"last_change_date": "2025-12-17T21:49:50.609Z",
"site_name": "string",
"site_id": "string",
"customer_id": "string",
"customer_name": "string",
"delivery_window_start": "2025-12-17T21:49:50.609Z",
"delivery_window_end": "2025-12-17T21:49:50.609Z",
"products": [
{
"product_id": "string",
"product_name": "string",
"quantity": 0,
"island": "string",
"compartment_index": 0
}
],
"extra_data": {},
"status": "string"
}
]
Validation Error
- application/json
- Example (from schema)
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}