Bol Save Ep

POST 
/v1/order/save_bol

Save Bill of Lading

Saves a Bill of Lading (BOL) for an order and sends it to the destination system.

Required Scopes (order:save_bol)

Headers

Header	Type	Required	Description
X-Tenant-Name	str	No	Name of the origin tenant making the request
X-Dest-Tenant-Name	str	Yes	Name of the destination tenant that will receive the BOL
X-Origin-System-Name	str | None	No	Name of the origin system. If not provided, uses the tenant's primary system

Request

order: OrderKey
Identifies the order this BOL belongs to. At least one field is required.

Show Child Attributes

origin_order_number: str | None = None
Order number from the origin system.

---

destination_order_number: int | None = None
Order number in the destination system.

---

order_id: str | None = None
ID of the order.

---

bol_number: str
Bill of Lading number identifier.

---

terminal: TerminalMappingKey
Terminal where the BOL originated. 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[BOLDetailRequest]
List of BOL line items. Each detail represents a distinct product/supplier combination on the BOL.

Show Child Attributes

supplier: CounterpartyMappingKey
Supplier for 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 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.

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.

---

bol: CrossroadsBOL | None = None
The saved BOL record.

Show Child Attributes

bol_number: str
Unique Bill of Lading identifier.

---

terminal: TerminalMappingKey
Terminal where the product was picked up. At least one of mapping_id, source_name, source_id, or goid must be provided.

---

bol_date: datetime
Date and time the BOL was issued.

---

details: list[BOLDetail]
Line items on the BOL.

---

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

Responses

200

Successful Response

422

Validation Error

application/json

Example (from schema)

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

Loading...