General Information about the Booking History API
What is Booking History:
The Booking History API provides a comprehensive record of all transactions affecting a customer's inventory. This includes transacion types such as Bills of Lading (BOLs), Reconsignments, Status Changes, Product Transfer Orders (PTO), and others (full list at bottom of page)
Notes:- Booked Barrels: Only barrels that have been booked are displayed.
- Pending Transactions: Transactions that are pending and not yet booked will not appear in the Booking History report.
- Time Information: The time for each transaction is based on the location where it occurs. All Booking times are recorded in Central Time, reflecting the booking location in Tulsa, OK. However, BOLs reflect the local time of the relevant terminal. Consequently, transactions in the Mountain Time Zone will show booking and transaction times that are at least one hour apart.
- More Details: GetBookingHistory in the Swift Developers Portal:
(Magellan Midstream Partners Developer Portal - Log in required)
Note on the potential of excessive data being generated by Booking History endpoint:
- The Booking History endpoint returns data for the last 30 days by default if no dates are specified. This limitation helps prevent excessive responses and reduces the risk of request timeouts.
- Date ranges exceeding 30 days may generate too much data, leading to potential timeouts and no data being returned.
Results:
id: Unique ID for the Booking History report
transactionID: This identifier represents the specific transaction number each of the transactions that have been made by each company in the time frame of the report.
Examples:
- Booking History Transaction ID 1234567 = Reconsignment ID 1234567
- Booking History Transaction ID 654321 = Bill of Lading Number 654321
Note: The TransactionID can be used to link the Booking History output to other transaction type reports, such as Bills of Lading (BOL), since the Reference ID is the transaction ID for transaction types.
shipmentRequestId: The transaction identifier for the shipment that moved the product from its origin into the ONEOK Refined system.
inventoryOwner ID & Name - "ABC OIL"/"123" Inventory Owner and affiliate ID of the specific transaction
transactionType: Transaction types are BOLs (Bills of Lading), PTO (product transfer orders), Receipts, Reconsignments, Shipments, Offlines, Settlements and Adjustments are the most common.
These reports are similar to the AIM201D1 report in the Magellan Portal Reporting App.
A more complete list of transaction types with a short definition is listed below.
FTP/Reporting App to API Mapping
Sample Mapping is for a Reconsignment Transaction - Other transaction types may have other fields
- BH.DAT (FTP) - Left
- GetBookingHistory (Inventory) - Right
-
Recommended: Version 3+
-
Transaction Types:
- BOL: BILL OF LADING
- Bill of Lading is a legally binding document that serves as a receipt and contract for fuel loaded or unloaded, detailing product type, volumes, destinations or source, carrier name, and all regulatory compliance language. It facilitates inventory tracking, invoicing, and ownership transfer.
- RCN: RECONSIGNMENT
- Reconsignment allow Inventory Owners to move their refined fuels from one location to another in the ONEOK refined fuel system. It also allows Inventory Owners to manage inventory volumes and meet their supplier’s demands at specific locations.
- STATCHANGE: STATUS CHANGE
- RCP: RECEIPT
-
An RCP is a receipt is used to verify and document receipt of refined fuel products. It ensures accurate tracking of inbound shipments, confirming product type, volumes, and origin.
Receipts play a crucial role in inventory management, regulatory compliance, and operational efficiency, helping shippers and terminal operators maintain precise records of fuel movements.
-
- GT: GRADE TRANSFER
- Grade transfer refers to the movement of fuel from one product grade to another within storage or distribution networks. This can involve reclassifying inventory, blending fuels to meet specifications, or shifting product between tanks to optimize supply.
- PTO-TO: PRODUCT TRANSFER ORDER - TO
- Product Transfer Order (PTO) - TO refers to the process of transferring ownership of fuel barrels to another inventory owner at a specific location within the system. It ensures accurate tracking of product movements and facilitates seamless transactions between parties.
- PTO-FROM: PRODUCT TRANSFER ORDER - FROM
- Product Transfer Order (PTO) - FROM refers to the process of transferring ownership of fuel barrels from one inventory owner to another at a specific location within the system. It ensures accurate tracking of product movements and facilitates seamless transactions between parties.
- ADJ: ADJUSTMENT
- Adjustment refers to a modification in inventory records due to discrepancies, reclassifications, or corrections in product volumes. Adjustments can occur for various reasons, such as measurement variances, accounting reconciliations, or operational changes.
- OFL: OFFLINE
- Offline transactions originate or terminate at a location that is not a ONEOK owned and operated facility, like an airport or another pipeline provider.
- TND: TENDER DEDUCTION - TIME BASED
-
Tender Deduction – Time Based refers to a volume deduction applied to product shipments based on the time the product remains in the system. This deduction accounts for inherent losses such as evaporation, shrinkage, or interface mixing that can occur over time during transport.
-
- SHP: SHIPMENT
- A shipment transaction is a movement refined or crude product between an origin and a destination point.
- DLV: DELIVERY
- A delivery is the physical transfer of product from ONEOK’s system to a shipper’s designated destination point
- STL: SETTLEMENT
- A Settlement is the process of reconciling the actual volume and quality of product delivered versus what was tendered or scheduled.
- TND-AUTO: TENDER DEDUCTION - AUTOMATI
-
Tender Deduction – Automatic is a fixed volume deduction applied automatically to all products tendered for transportation.
A tender deduction of one-tenth of one percent (0.1%) by volume is made on the products transported from all Origins.
-
- TND-MANUAL: TENDER DEDUCTION - MANUAL
-
Tender Deduction – Manual is a “manual” tender deduction that refers to a non-standard or route-specific volume deduction that’s explicitly defined in a particular tariff items — rather than applied automatically across all shipments.
-
- SET OFF: STOF
- Set-off is a financial or volumetric adjustment where one party’s obligation is offset by a corresponding credit or claim—like deducting over-delivered volumes from a future shipment or reconciling charges across accounts.
Swift - Booking History
Booking History is available in Swift for viewing on screen or downloading in Excel or CSV
1) Inventory on Swift Home page
2) Inventory Dashboard
3) Inventory Reports tab
- Report Type, choose Booking History.
- Add a data range, select Pipeline System and Product Group. In order to see any transactions returned all fields need to be selected.
Reference ID in Swift = Transaction ID which is the transaction number of the source transaction.
