Developer Guide

Importing Orders, Loads and Shipments

Overview

Import the orders, loads and shipments you expect at your facilities so Conduit can use them when appointments are booked.

Conduit calls each of these records an order, but an order can represent anything carriers book against in your system: a purchase order, sales order, load or shipment. This guide and the API use "order" for all of them.

Importing your orders lets Conduit:

  • Validate reference IDs. Carriers can only book with a PO#, SO#, load number, shipment ID or other reference ID that matches one of your orders.
  • Fill in appointment details. Carrier, shipper or receiver, customer, items and load types come from the order instead of being typed in by hand.
  • Hold appointments until an order is ready. Conduit doesn't offer appointment times before an order's earliest scheduled start time.

Orders usually come from your TMS, WMS or ERP. You can send them as a CSV file or one at a time through the REST API, and we can build custom integrations for other sources.

Choosing what to import

Import one order for each thing carriers book appointments against, and use the ID carriers and drivers will have on hand as its reference ID. For example:

If carriers book by Import each Reference ID
Purchase order Purchase order PO number
Sales order Sales order SO number
Load Load Load number
Shipment Shipment Shipment ID

If carriers might quote a different ID for the same order, such as a BOL number or your system's internal ID, add it as the external reference ID or a custom reference. Conduit matches those too.

How orders are used

Matching reference IDs to orders

When a carrier, driver or facility staff member enters a reference ID, such as a PO number, Conduit looks for a matching order at that facility. It checks every ID you've given the order, not just its main reference ID.

Once a reference ID matches, the appointment is linked. An appointment can include several orders, and an order can be included on more than one appointment.

Reference ID validation

Facilities can require carriers to book with a reference ID that matches one of your orders. This stops appointments from being booked against orders that don't exist. Validation can be turned on separately for inbound and outbound appointments, and the facility can choose how the reference ID field is labelled, such as "PO Number". Contact us to change these settings.

If you book appointments from your own system, use Validate Reference Ids to check reference IDs before booking.

Filling in appointment details

When a reference ID matches an order, Conduit fills in the appointment's details, such as the carrier, shipper or receiver, customer and load types, from the order. Carriers and facility staff don't have to type them in, and they match what's in your system.

When you book through Request FacilityAppointment, include the appointment's details in the request.

Changing an order after an appointment is booked doesn't update the appointment.

Earliest scheduled start time

If an order can't be picked up or delivered before a certain date, such as a ready-by date, give it an earliest scheduled start time. Conduit won't offer appointment times before it.

If you book appointments from your own system, choose a time from Get Facility Availability so the earliest scheduled start time is respected.

Fields

Field CSV column REST API field Custom integration Description Required
Reference ID Reference ID reference_id ✓ The ID carriers and drivers use for the order, such as a PO#, SO#, load number or shipment ID. Yes
Facility ID Facility ID facility_id ✓ The facility the order belongs to, as returned by List Facilities. Yes
Direction Direction type ✓ Inbound or Outbound. Leave it blank if the order can go either way. CSV: No
API: Yes
External Reference ID External Reference ID external_reference_id ✓ Another ID carriers might use for the order, such as your system's internal ID. No
Load Type Load Type load_type_name ✓ A load type set up for the facility, such as Dry Van. No
Earliest Scheduled Start Time Earliest Scheduled Start Time earliest_scheduled_start_time ✓ The earliest date and time the order can be booked. No
Item IDs Item IDs item_ids ✓ What's in the order, such as SKUs or item numbers. No
Shipper Receiver Shipper Receiver shipper_receiver ✓ The shipper for inbound orders, or the receiver for outbound orders. No
Carrier Carrier carrier ✓ The carrier for the order. No
Carrier SCAC Carrier SCAC carrier_scac ✓ The carrier's SCAC code. No
Carrier Emails Carrier Emails — ✓ The carrier's email addresses, separated by commas. Not available through the REST API. No
Customer Customer customer ✓ The customer the order is for, commonly used by 3PLs. No
Notes Notes notes ✓ Notes to show in Conduit. No
Custom references One column per reference type order_reference_types ✓ Other IDs set up for your organization. See Custom references. No

Formatting tips

  • Dates and times: use ISO 8601 with a time zone offset, for example 2025-01-08T08:00:00-08:00.
  • Direction: write Inbound or Outbound with a capital letter.
  • Facility IDs: copy them exactly as Conduit returns them.

Custom references

If your orders have more than one ID carriers might use, such as a BOL number alongside a PO# or load number, Conduit can set up custom references for your organization. Carriers and drivers can then find an order by any of them. Contact us at [email protected] to set them up.

Sending orders

Custom integrations

Conduit can receive orders straight from your systems through:

  • Direct integrations with your TMS, WMS or ERP
  • CSV files delivered over SFTP
  • EDI

Contact us at [email protected] to discuss a custom integration. You can also send orders yourself with a CSV upload or the REST API.

CSV upload

Upload a CSV file to Upload Orders.

  • Columns: include Reference ID and Facility ID, plus any other columns from the Fields table. Column names aren't case-sensitive.
  • Facilities: one file can include orders for several facilities.
  • Format: save the file as UTF-8 without a byte order mark, and don't include blank lines.

If any row has a problem, nothing in the file is saved and the response explains what to fix.

Example CSV

This example includes a purchase order, a sales order, a load and a shipment:

Reference ID,External Reference ID,Facility ID,Direction,Load Type,Earliest Scheduled Start Time,Item IDs,Shipper Receiver,Carrier,Carrier Emails,Customer,Notes
PO-10045,ERP-55821,0db07caf-5005-4144-a983-e210c96cd451,Inbound,Dry Van,2025-01-08T08:00:00-08:00,"SKU-1, SKU-2",Sierra Bottling,Ftl Trucks,"[email protected],[email protected]",Globex,Deliver to dock 4
SO-20981,,0db07caf-5005-4144-a983-e210c96cd451,Outbound,,,SKU-3,Acme Foods,,,,
LOAD-58213,TMS-88120,0db07caf-5005-4144-a983-e210c96cd451,Inbound,,,,Sierra Bottling,Ftl Trucks,,,Mixed pallets from two POs
SHP-4471,,0db07caf-5005-4144-a983-e210c96cd451,Outbound,,2025-01-10T06:00:00-08:00,,Acme Foods,,,,

You can also download complete examples:

Full and partial uploads

By default, each upload replaces the orders for every facility in the file. Orders that aren't in the file are removed, so always send the complete list of open orders. Facilities that aren't in the file, and appointments that are already booked, aren't affected.

If you'd rather send only new and changed orders, Conduit can set up partial uploads for your organization instead. Contact us at [email protected] to discuss.

REST API

To send one order at a time, use Create (or Update) Order. If the facility already has an order with the same reference ID, it's replaced, so send every field each time.

Previous
Webhooks
Next
SSO