Order Create Ep

POST /v1/order/create

Create Order

Creates a new order in Crossroads and sends it to the destination system.

Required Scopes (order:create)

Headers

Header	Type	Required	Description
X-Tenant-Name	str	No	Name of the origin tenant making the request. Optional if you are authenticated by API key.
X-Origin-Instance-Name	str \| None	No	Name of the instance creating the request. Optional if you are authenticated by API key.
X-Dest-Tenant-Name	str	Yes	Name of the destination tenant that will receive the request

Request

origin_order_number: str
Order number from the origin system.

po: str | None = None
Purchase order number.

supply_owner: MappingKey | None = None
The company responsible for supply.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

delivery_window: DeliveryWindow
Time window for delivery.

Show DeliveryWindow Attributes

start: datetime
Start of delivery window.

end: datetime
End of delivery window. End date must be after start date.

timezone: str = "UTC"
Timezone name.

note: str | None = None
Order notes (max 300 characters).

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: SiteTankMappingKey
Delivery site reference. Either tank_id on the site or product on the drop must be provided for tank resolution.

Show SiteTankMappingKey Attributes

To choose site, at least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id. To choose tank, at least one of tank_id or product_source_id must be provided. Crossroads recommends that you provide tank_id. If you provide product_source_id, only tanks that have a product ID can be chosen. If two tanks have the same product ID, the one with the lowest ID will be chosen.

source_id: str | None = None
Unique identifier of the site in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the site in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the site mapping record. Use when you have previously looked up or cached the mapping.

tank_id: str | None = None
Tank ID of the tank to be selected. Matched against the tanks at the site.

product_source_id: str | None = None
Product ID for a product contained in a tank at the site.

product: ProductMappingKey | None = None
Product being delivered. Required if tank_id is not provided on the site.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

volume: int
Volume to deliver in gallons.

extra_data: dict = {}
Additional custom data for this drop.

loads: list[Load] = []
Supply source instructions for this drop. Each load specifies where and how product will be sourced. A load is considered fully qualified when terminal, product, supplier, and price_type are all provided.

Show Child Attributes

terminal: TerminalMappingKey | None = None
Loading terminal for pickup.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

product: ProductMappingKey | None = None
Product to load.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

supplier: CounterpartyMappingKey | None = None
Supplier providing the product.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

price_type: PriceType | None = None
Pricing methodology for the supply option.

rack - Spot rack price at the terminal.

contract - Negotiated contract price.

index - Index-based pricing (e.g., OPIS).

inventory - Priced from existing inventory.

spot - Spot market price.

contract: str | None = None
Contract identifier when price_type is "contract". Max 100 characters.

extra_data: dict = {}
Additional metadata for the order. This can be used to pass custom information to the destination system or for retrieval later.

units: VolumeUnits = "gallons"
Volume units for the order. Accepted values: "gallons" (default), "liters".

created_by_hauler: bool
Indicates whether the creating tenant is the hauler. If true, the origin tenant is the hauler and the destination tenant is being hauled for. If false, the destination tenant is the hauler and the origin tenant is being hauled for.

Response

status: str
Crossroads integration status. Each status represents a step in the integration pipeline.

Integration Stages

pending
The request has been accepted and is being processed asynchronously.

requested
The order has been created and is awaiting manual acceptance by the destination tenant.

origin_mapped
The order has been received by crossroads and needs mapping to crossroads master data.

master_mapped
The order has been mapped to crossroads master data and needs mapping to the destination system.

destination_mapped
The order has been mapped to the destination system and is ready to be sent.

synced
The order has been successfully sent to the destination system.

canceled
The order has been canceled.

error
An error occurred during processing. Check the message and log for details.

rejected
The order was rejected by the destination system. Check the message and log for details.

message: str | None = None
Status message or error details.

log: CrossroadsLogV2 | None = None
Processing log entry.

order: Order
The created order object.

Show Order Attributes

origin_order_number: str
Order number from the origin system.

destination_order_number: str | None = None
Order number assigned by the destination system after being received.

po: str | None = None
Purchase order number.

supply_owner: CounterpartyMappingKey | None = None
The company responsible for supply.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

delivery_window: DeliveryWindow
Time window for delivery.

Show DeliveryWindow Attributes

start: datetime
Start of delivery window.

end: datetime
End of delivery window. End date must be after start date.

timezone: str = "UTC"
Timezone name.

note: str | None = None
Order notes (max 300 characters).

drops: list[Drop]
List of delivery drops on the order.

Show Child Attributes

site: SiteTankMappingKey
Delivery site reference. Either tank_id on the site or product on the drop must be provided for tank resolution.

Show SiteTankMappingKey Attributes

source_id: str | None = None
Unique identifier of the site in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the site in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the site mapping record. Use when you have previously looked up or cached the mapping.

tank_id: str | None = None
Tank ID of the tank to be selected. Matched against the tanks at the site.

product_source_id: str | None = None
Product ID for a product contained in a tank at the site.

product: ProductMappingKey | None = None
Product being delivered. Required if tank_id is not provided on the site.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

volume: int
Volume to deliver in gallons.

extra_data: dict = {}
Additional custom data for this drop.

Show Child Attributes

terminal: TerminalMappingKey | None = None
Loading terminal for pickup.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

product: ProductMappingKey | None = None
Product to load.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

supplier: CounterpartyMappingKey | None = None
Supplier providing the product.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

price_type: PriceType | None = None
Pricing methodology for the supply option.

rack - Spot rack price at the terminal.

contract - Negotiated contract price.

index - Index-based pricing (e.g., OPIS).

inventory - Priced from existing inventory.

spot - Spot market price.

contract: str | None = None
Contract identifier when price_type is "contract". Max 100 characters.

bols: list[BOL] = []
Bills of Lading associated with completed deliveries. BOLs provide proof of shipment and delivery details.

Show Child Attributes

bol_number: str
Unique Bill of Lading identifier issued by the carrier or terminal.

terminal: TerminalMappingKey
Loading terminal where product was picked up.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

bol_date: datetime
Date and time the BOL was issued.

details: list[BOLDetail]
Line items on the BOL. Each detail represents a distinct product/supplier combination on the BOL.

Show BOLDetail Attributes

site: SiteTankMappingKey
Delivery site for this line item.

Show SiteTankMappingKey Attributes

source_id: str | None = None
Unique identifier of the site in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the site in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the site mapping record. Use when you have previously looked up or cached the mapping.

tank_id: str | None = None
Tank ID of the tank to be selected. Matched against the tanks at the site.

product_source_id: str | None = None
Product ID for a product contained in a tank at the site.

supplier: CounterpartyMappingKey
Supplier of the product on this line item.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

product: ProductMappingKey
Product supplied on this line item.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

contract: str | None = None
Contract identifier if this line item was sourced under a contract.

price_type: PriceType | None = None
Pricing methodology for this line item.

rack - Spot rack price at the terminal.

contract - Negotiated contract price.

index - Index-based pricing (e.g., OPIS).

inventory - Priced from existing inventory.

spot - Spot market price.

net_volume: float
Net volume delivered in gallons. This is the actual fuel volume after temperature correction.

gross_volume: float
Gross volume in gallons. Measured volume before temperature correction.

bol_photos: list[BOLPhotoReference] = []
References to BOL photos stored in the system.

Show BOLPhotoReference Attributes

bol_number: str
BOL number this photo is associated with.

file_name: str
File name of the stored photo.

uploaded_at: datetime
When the photo was uploaded.

note: str | None = None
Optional note about the photo.

executed_drops: list[ExecutedDrop] = []
Drop measurement records for completed deliveries.

Show ExecutedDrop Attributes

site: SiteMappingKey
Delivery site where the drop was executed.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

mode: str
How to apply this record. "replace" replaces existing records for this site, "append" adds to them.

details: list[ExecutedDropDetail]
Individual product measurements for this drop.

Show Child Attributes

product: ProductMappingKey
Product being dropped.

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

quantity: float
Volume delivered in gallons.

tank: SiteTankMappingKey | None = None
Tank where the product was dropped.

Show SiteTankMappingKey Attributes

source_id: str | None = None
Unique identifier of the site in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the site in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the site mapping record. Use when you have previously looked up or cached the mapping.

tank_id: str | None = None
Tank ID of the tank to be selected. Matched against the tanks at the site.

product_source_id: str | None = None
Product ID for a product contained in a tank at the site.

pre_drop_volume: float | None = None
Tank volume in gallons before delivery.

pre_drop_inches: float | None = None
Tank stick measurement in inches before delivery.

pre_drop_time: datetime | None = None
Time of pre-drop measurement.

post_drop_volume: float | None = None
Tank volume in gallons after delivery.

post_drop_inches: float | None = None
Tank stick measurement in inches after delivery.

post_drop_time: datetime
Time of post-drop measurement.

extra_data: dict = {}
Additional custom data from the source system. This data will be preserved on the order.

Responses

Successful Response

Validation Error

application/json

Example (from schema)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Order Create Ep

/v1/order/create

Create Order

Headers​

Request​

Response​

Responses​

Headers

Request

Response

Responses