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	Yes	Name of the origin tenant making the request
X-Dest-Tenant-Name	str	Yes	Name of the destination tenant that will receive the order
X-Origin-System-Name	str \| None	No	Name of the origin system. If not provided, uses the tenant's primary system

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 Child Attributes

mapping_id: str | None = None
ID of the mapping record.

source_name: str | None = None
Name in the source system.

source_id: str | None = None
ID in the source system.

goid: str | None = None
Gravitate Object ID (master data reference).

delivery_window: DeliveryWindow
Time window for delivery.

Show Child Attributes

start: datetime
Start of delivery window.

end: datetime
End of delivery window.

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: SiteMappingKey
Site identifier for the location of the drop. At least one of mapping_id, source_name, source_id, or goid must be provided.

product: ProductMappingKey | None = None
Product to deliver. At least one of mapping_id, source_name, source_id, or goid must be provided.

volume: int
Volume to deliver.

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.

Blends

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: TerminalMappingKey
Terminal to load supply at. At least one of mapping_id, source_name, source_id, or goid must be provided.

product: ProductMappingKey | None = None
Product to be loaded. At least one of mapping_id, source_name, source_id, or goid must be provided. This should only be set when creating blends. See Blends below for more information.

supplier: CounterpartyMappingKey
Supplier to be used for the supply option. At least one of mapping_id, source_name, source_id, or goid must be provided.

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.

index
Specifies that the supply option must be sourced from an index price.

inventory
Specifies that the supply option must be sourced from an inventory price.

spot
Specifies that the supply option must be sourced from a spot price.

contract: str | None = None
The contract to be used for the supply option.

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

Response

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

Integration Stages

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.

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.

order: Order
The created order object.

Show Child 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. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: company_XXXXXX.

delivery_window: DeliveryWindow
Time window for delivery.

Show Child Attributes

start: datetime
Start of delivery window.

end: datetime
End of delivery window.

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: SiteMappingKey
Delivery site reference. At least one of mapping_id, source_name, source_id, or goid must be provided. If using mapping_id, source_name, or source_id, tank_id is required. If using goid, tank_goid is required.

Show Child Attributes

mapping_id: str | None = None
ID of the mapping record. Use when you have previously looked up or cached the mapping. Requires tank_id to be set.

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided except tank_goid. Format: site_XXXXXX.

tank_id: str | None = None
Tank identifier at the site in the source system. Required when using mapping_id, source_name, or source_id. Max 10 characters.

tank_goid: str | None = None
Tank Gravitate Object ID. Required when using goid. Format: tank_XXXXXX. Max 50 characters.

product: ProductMappingKey | None = None
Product being delivered. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: product_XXXXXX.

volume: int
Volume to deliver in gallons.

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. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: terminal_XXXXXX.

product: ProductMappingKey | None = None
Product to load. Only set when creating blends - otherwise inherited from drop. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: product_XXXXXX.

supplier: CounterpartyMappingKey | None = None
Supplier providing the product. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: company_XXXXXX.

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. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: terminal_XXXXXX.

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 Child Attributes

supplier: CounterpartyMappingKey
Supplier of the product on this line item. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: company_XXXXXX.

product: ProductMappingKey
Product supplied on this line item. At least one of mapping_id, source_name, source_id, or goid must be provided.

Show Child Attributes

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

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

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

goid: str | None = None
Gravitate Object ID - direct reference to master data. When set, no other fields can be provided. Format: product_XXXXXX.

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.

extra_data: dict = {}
Additional custom data from the source system.

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

log: CrossroadsLogV2 | None = None
Processing log entry.

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