Order Create Ep
POST/v1/order/create
Create an Order
reference_order_number: str
External order number attached to the order to be used as a reference for an outside system.
supply_owner: Counterparty | None = None
The Supply Owner to pull supply options from.
If not set, the system defaults to the Supply Owner of the first drop site on the request.
Supply options are segmented by a counterparty called the Supply Owner. The Supply Owner can be configured at the site level and controls which pool of supply options are allowed to be used for orders going to that site. Supply Owners are typically used when a client is managing sites for multiple customers and wants to ensure that each customer only has access to their own supply options.
Show Child Attributes
In order to match a counterparty one of the three identifying keys are required. Counterparty will be matched in the following hierarchy: (source_system and source_id), id, name. Source system and source_id are set as extra_data on Counterparty objects in order to create an external reference to the counterparty.
id: str | None = None
Unique identifier for the counterparty.
name: str | None = None
Name of the counterparty.
source_system: str | None = None
The name of the external system this Counterparty is integrated from.
source_id: str | None = None
The unique identifier for this Counterparty in the source_system.
sourcing_strategy: SourcingStrategy | None = None
Defines the strategy for how the order is sourced.
If the sourcing strategy is not set it will default to the Supply Owner's default strategy.
Sourcing Strategy
Specific Supply
Will only create an order if the requested supply resolves to a single supply option.
This is ideal for orders requiring a specific type of supply without alternatives.
Tank Supply Default
Will only create an order if the requested drops have a default supply option configured in the system.
This strategy ensures orders are fulfilled using pre-defined supply preferences.
Use Best
Will resolve supply options using the supplied parameters and then choose the best supply option from the remaining choices.
This strategy optimizes for cost and availability when a specific supply is not required.
Manual
Will submit a request to have an order manually created.
This option is used when automated processes cannot meet the specific needs of the order or when human intervention is preferred for decision-making.
manual_supply_fallback: bool = True
Indicates if a manual request should be submitted when the order cannot be automatically sourced.
allow_alternate_products: bool = False
Determines whether alternate products can be used as substitutes for the requested products.
delivery_window: DeliveryWindow
Specifies the delivery window for the order, defaulting to UTC.
Show Child Attributes
start: datetime
Start of the delivery window.
end: datetime
End of the delivery window.
timezone: str = "UTC"
Timezone for the delivery window. Defaults to UTC.
note: str | None = None
An optional note to be included with the order.
drops: list[Drop]
The list of drops to be made on this order.
Each drop corresponds to a specific product being dropped into a tank at a site.
Show Child Attributes
site: Site
The site identifier for the drop request, specifying the location of the drop.
Show Child Attributes
In order to match a site one of the three identifying keys are required. The site will be matched in the following hierarchy: (source_system and source_id), id, name. Source system and source_id are set as extra_data on sites in order to create an external reference to the site.
id: str | None = None
Unique identifier for the site.
number: str | None = None
Site number.
source_system: str | None = None
The name of the external system this Site is integrated from.
source_id: str | None = None
The unique identifier for this Site in the source_system.
tank_id: str | None = None
Identifies the tank to drop the product into.
If tank_id is not set the system will default to the first tank containing the requested product at that site.
If a tank_id is set and a product is not specified the system will use the product contained in the specified tank.
product: Product
The product to be delivered to the site. If a tank_id is set the specified product must contain that product.
If not set then a tank_id must be specified in order to default the product.
Show Child Attributes
In order to match a product one of the three identifying keys are required. The product will be matched in the following hierarchy: (source_system and source_id), id, name. Source system and source_id are set as extra_data on products in order to create an external reference to the product.
id: str | None = None
Unique identifier for the product.
name: str | None = None
Name of the product.
source_system: str | None = None
The name of the external system this product is integrated from.
source_id: str | None = None
The unique identifier for this product in the source_system.
volume: int
The requested volume of the product to be delivered. The system will auto-fit the requested volume to the nearest available trailer.
If no viable trailers can be used to fulfill the request the order will fail to supply.
loads: list[Load] = []
The supply parameters used to load the requested product. The supply parameters are treated as filters to the pool of available supply options.
If a parameter is left unfilled the system will assume that any value is acceptable for that parameter.
For example sending a terminal with no supplier will allow any supplier to be used at the specified terminal.
See Sourcing Strategy for more information on how the system resolves supply options.
In order to create blends multiple loads can be sent. The system will attempt to source the final product by loading the requested component products. If multiple loads are sent each load must have the same types of keys specified. For example, if one load has a supplier all loads must have a supplier specified.
Blends will be created using the component products and blended according to the blend ratios defined on final product.
Show Child Attributes
terminal: Terminal | None = None
The terminal to be used for the supply option. If not set the system will default to the terminal with the most available supply options.
product: Product | None = None
The product to be used for the supply option. This should only be set when creating blends. See Blends below for more information.
Show Child Attributes
In order to match a product one of the three identifying keys are required. The product will be matched in the following hierarchy: (source_system and source_id), id, name. Source system and source_id are set as extra_data on products in order to create an external reference to the product.
id: str | None = None
Unique identifier for the product.
name: str | None = None
Name of the product.
source_system: str | None = None
The name of the external system this Product is integrated from.
source_id: str | None = None
The unique identifier for this Product in the source_system.
supplier: Counterparty | None = None
The supplier to be used for the supply option. If not set the system will default to the supplier with the most available supply options.
Show Child Attributes
In order to match a counterparty one of the three identifying keys are required. Counterparty will be matched in the following hierarchy: (source_system and source_id), id, name. Source system and source_id are set as extra_data on Counterparty objects in order to create an external reference to the counterparty.
id: str | None = None
Unique identifier for the counterparty.
name: str | None = None
Name of the counterparty.
source_system: str | None = None
The name of the external system this Counterparty is integrated from.
source_id: str | None = None
The unique identifier for this Counterparty in the source_system.
price_type: str | None = None
The price type to be used for the supply option.
contract
Specifies that the supply option must be sourced from a contract.
rack
Specifies that the supply option must be sourced from rack.
contract: str | None = None
The contract to be used for the supply option.
accept_by: datetime | None = None
Specifies the date this delivery request must be accepted by
extra_data: dict | None_ = None
Any additional data provided or managed by the client through integration endpoints.
Response
status: Status
The status of the order creation request.
Indicates whether an order was successfully created or an error occurred.
Show Statuses
Order Successfully Created
The order was successfully sourced and created.
Response will include the order payload and the corresponding order number generated.
Order Requested. Awaiting manual sourcing
Sourcing strategy manual was used. An order request was created.
The order will need to be manually sourced and created.
Order could not be sourced. Request created for manual sourcing
The order could not be sourced and the manual fallback was allowed.
An order request was submitted to be manually fulfilled.
Order could not be sourced and no fallback allowed
The order could not be sourced and the manual fallback was not allowed.
No order or request created. Request will need to be re-submitted
Order could not be created. See errors for more info.
There was an unhandled failure that prevented the order from being created.
The errors list will provide more information on what went wrong.
order_number: int | None = None
The order number generated for the created order.
If the order was not created this field will be empty.
order: Order | None = None
The order payload that was created. See Get Order for more information on the order payload.
If the order could not be created or a request was filed as a fallback this field will be empty.
errors: list[str]
A list of errors that occurred during the order creation process.
accept_by: datetime | None = None
the datetime from the request is sent in the response
reference_order_number: str
External order number attached to the order to be used as a reference for an outside system.
Responses
- 200
- 422
Successful Response
- application/json
- Example (from schema)
{
"status": "Order Successfully Created",
"order_number": 0,
"order": {
"timezone_data": {},
"id": "string",
"revision": "string",
"number": 0,
"po": "string",
"state": "string",
"type": "string",
"sector": "string",
"affected_tanks": [
{
"store": "string",
"tanks": [
{
"current_volume": 0,
"percent_filled": 0,
"product": "string",
"projected_percent_filled": 0,
"projected_volume": 0,
"run_out_date": "2025-12-17T21:49:50.661Z",
"run_out_date_with_drops": "2025-12-17T21:49:50.661Z",
"storage_max": 0,
"store_number": "string",
"tank_id": 0,
"tank_size": 0,
"model_target_min": 0,
"model_target_max": 0,
"market": "string",
"is_overridden": true,
"as_of": "2025-12-17T21:49:50.661Z",
"monitoring_strategy": "Manual Tank Readings",
"manifold_id": "string",
"site_notes": "string"
}
]
}
],
"assigned_driver": "string",
"assigned_drivers": [
"string"
],
"assigned_driver_schedule_id": "string",
"assigned_driver_schedules": [
"string"
],
"carrier_code": "string",
"carrier": "string",
"customer": "string",
"freight_customers": [
{
"name": "string",
"id": "string"
}
],
"freight_undefined": false,
"carrier_window_start": "2025-12-17T21:49:50.661Z",
"carrier_window_end": "2025-12-17T21:49:50.661Z",
"carrier_window_override": false,
"carrier_notify_state": "none",
"default_carrier_window_start": "2025-12-17T21:49:50.661Z",
"default_carrier_window_end": "2025-12-17T21:49:50.661Z",
"carrier_info": {
"name": "string",
"counterparty_id": "string",
"notify_state": "none",
"updated": "2025-12-17T21:49:50.661Z",
"rejected_reason": "string",
"window_start": "2025-12-17T21:49:50.661Z",
"window_end": "2025-12-17T21:49:50.661Z",
"email_sent": "2025-12-17T21:49:50.661Z",
"code": "string",
"type": "legacy",
"crossroads_status": "accepted",
"crossroads_received_at": "2025-12-17T21:49:50.661Z",
"crossroads_queued_update": {
"id": "string",
"created_by": "string",
"created_date": "2025-12-17T21:49:50.661Z",
"status": "requested"
},
"owner_system_id": "string",
"owner_system_name": "string",
"owner_order_number": 0,
"owner_order_id": "string",
"worker_order_number": 0,
"worker_order_id": "string",
"worker_system_id": "string",
"worker_system_name": "string",
"client_goid": "string",
"client_name": "string"
},
"compartments": [
{
"compartment_index": 0,
"product_short_name": "string",
"product_name": "string",
"store_number": "string",
"targets": [
{
"location_name": "string",
"store_number": "string",
"tank_id": 0,
"manifold_id": "string",
"volume": 0,
"is_error": false
}
]
}
],
"terminal1_counterparty": "string",
"destination_counterparty": "string",
"dispatch_window_end": "2025-12-17T21:49:50.661Z",
"dispatch_window_start": "2025-12-17T21:49:50.661Z",
"drops": [
{
"location_name": "string",
"location_id": "string",
"site_notes": "string",
"address": "string",
"city": "string",
"postal_code": "string",
"phone": "string",
"state": "string",
"store_number": "string",
"counterparty": "string",
"store_name": "string",
"details": [
{
"product_name": "string",
"product_id": "string",
"tank_id": 0,
"sources": [
{
"volume": 0,
"compartment_index": 0
}
],
"volume": 0,
"uuid": "string"
}
],
"driver": "string",
"driver_schedule_id": "string",
"completed_at": "2025-12-17T21:49:50.661Z"
}
],
"estimated_travel_time": 0,
"loads": [
{
"location_name": "string",
"location_short_name": "string",
"location_id": "string",
"address": "string",
"city": "string",
"state": "string",
"postal_code": "string",
"driver": "string",
"driver_schedule_id": "string",
"details": [
{
"product_name": "string",
"product_id": "string",
"counterparty": "string",
"counterparty_id": "string",
"supply_owner": "string",
"supply_owner_id": "string",
"curve_id": "string",
"price_id": "string",
"group_id": "string",
"price_type": "string",
"contract": "string",
"window_start": "2025-12-17T21:49:50.661Z",
"window_end": "2025-12-17T21:49:50.661Z",
"volume": 0,
"targets": [
{
"volume": 0,
"compartment_index": 0
}
]
}
],
"completed_at": "2025-12-17T21:49:50.661Z"
}
],
"detours": [
{
"detour_id": "string",
"type": "no_load",
"location_name": "string",
"location_id": "string",
"completed_at": "2025-12-17T21:49:50.661Z",
"driver": "string",
"driver_schedule_id": "string",
"address": "string",
"city": "string",
"state": "string",
"postal_code": "string"
}
],
"load_type": "string",
"load_window_start": "2025-12-17T21:49:50.662Z",
"load_window_end": "2025-12-17T21:49:50.662Z",
"estimated_load_date": "2025-12-17T21:49:50.662Z",
"map_stops": [
{
"lat": 0,
"lng": 0
}
],
"product_ratios": [
{
"name": "string",
"amount": 0,
"volume": 0
}
],
"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.662Z",
"effective_to": "2025-12-17T21:49:50.662Z",
"group_id": "string",
"group_effective_cutover": "2025-12-17T21:49:50.662Z",
"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.662Z",
"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.662Z",
"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.662Z",
"requires_approval": false,
"requires_approval_reason_code": false,
"is_approved": false,
"approved_by": "string",
"approved_date": "2025-12-17T21:49:50.663Z",
"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.663Z",
"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.663Z",
"bol_number": "string",
"bol_number_override": "string",
"delivery_date": "2025-12-17T21:49:50.663Z"
}
],
"counterparty_id": "string",
"book_type": "Cost",
"effective_date_used": "2025-12-17T21:49:50.663Z",
"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"
},
"supply_owner_map": {
"definitions": [
{
"location_name": "string",
"product": "string",
"supply_owner_id": "string"
}
]
},
"total_gallons": 0,
"unload_time": 0,
"trip_status": "string",
"flags": [
{
"name": "string",
"type": "string",
"severity": "string",
"threshold": 0,
"details": [
{
"label": "string",
"value": "string",
"date": "2025-12-17T21:49:50.663Z",
"with_drops": false
}
],
"sub_flags": [
null
],
"updated_by": "string",
"updated": "2025-12-17T21:49:50.663Z",
"reason_code": "string",
"notes": "string"
}
],
"is_model_created": true,
"hauling_for": "string",
"hauling_for_id": "string",
"load_number": "string",
"load_numbers": [
"string"
],
"carrier_id": "string",
"manager_id": "string",
"manager": "string",
"is_short_load": true,
"last_supply_auto_update": "2025-12-17T21:49:50.663Z",
"supply_locked": false,
"market": "string",
"turn_time": "string",
"updated_by": "string",
"updated_on": "2025-12-17T21:49:50.663Z",
"created_date": "2025-12-17T21:49:50.663Z",
"created_by": "string",
"is_linked": true,
"note": {
"content": "string",
"updated_by": "string",
"updated_on": "2025-12-17T21:49:50.663Z"
},
"trailer_config": "string",
"carrier_window_eligible": false,
"can_cancel": false,
"can_reset": false,
"has_additives": true,
"is_by_product": false,
"allow_terminal_swaps": false,
"order_request_info": {
"site_number": "string",
"site_name": "string",
"site_id": "string",
"site_address": "string",
"site_city": "string",
"site_state": "string",
"number": 0,
"products": [
{
"product_id": "string",
"product_name": "string",
"quantity": 0,
"island": "string",
"compartment_index": 0
}
],
"customer_name": "string",
"customer_id": "string",
"created_date": "2025-12-17T21:49:50.663Z",
"delivery_window_start": "2025-12-17T21:49:50.663Z",
"delivery_window_end": "2025-12-17T21:49:50.663Z",
"status": "Pending",
"total_volume": 0
},
"has_supplier_emails": false,
"is_new_order": false,
"suppliers": [
"string"
]
},
"errors": [
"string"
],
"accept_by": "2025-12-17T21:49:50.663Z",
"reference_order_number": "string",
"extra_data": {}
}
Validation Error
- application/json
- Example (from schema)
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}