Overview
The OneRail Delivery API engine is your complete integration solution for sending orders through the platform, offering a focused and streamlined experience. In addition to accepting orders dynamically from your organization's chosen application, it is also capable of producing webhook requests which can automatically provide alerts for deliveries to connected applications.
An order is what we receive from a shipper, it represents the shipper's request and contains all the details needed to fulfill it. Deliveries are the individual shipments sent to make the order happen. When calling the API, both order and delivery details are provided together in the request body. All API interactions in this guide are built around this model.
Integrating your organization's operation via API allows for immediate processing and updates, without the need for manual intervention/monitoring.
Note: Generally, we want to first test our integration in a manner that will allow us to test various functionalities without impacting production operations. Ensure that any processes that would trigger an order to dispatch or be otherwise processed are disabled during any testing procedures.
Authentication
Client authentication with the OneRail API Engine can be classified by distinct two methods: user-based and org-based. The process of establishing authentication between your app and the OR API will depend on the desired auth method. The following subsections outline the steps to implement each of the available authentication methods:
User-Based Authentication
In this method, individual user credentials configured for your account are presented to the platform by your client application. Upon successful authentication, your client application would then act on the behalf of the user's credentials that were used to authenticate.
To perform authentication with this method, your client app will need to perform a POST request to the "user/authenticate" endpoint. This endpoint requires the desired user's username and their associated password.
Important: To use user-based authentication, the user must already be configured as a user on the OneRail platform before attempting to authenticate. If the user does not yet exist on the platform, contact your implementation manager to have the account created prior to integrating.
For full details regarding this endpoint, refer to the following Swagger reference:
POST/user/authenticateCreates and returns an authentication token
Parameters
No parameters
Request Bodyrequiredapplication/json
User credetials
{
"username": "string",
"password": "string",
"password_is_token": true
}| Field | Type | Description |
|---|---|---|
| usernamerequired | string | — |
| passwordrequired | string | — |
| password_is_token | boolean | — |
Responses
| Code | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 |
User token created
|
|||||||||||||||||||||
| 401 |
Unauthorized - invalid credentials
|
|||||||||||||||||||||
| default |
Unexpected error
|
Org-Based Authentication
Organization-based authentication utilizes a pair of values (App ID and API Key) that are attached to the header of requests intended for the OneRail API Engine. The App ID and API Key are created for each shipper on an individual basis by our product team and then distributed for production use. When using this method, any of your organization's applications connecting to the API will connect with a set of authentication credentials that represents each individual shipper.
To obtain the App ID and API Key for a shipper, you must first contact the OneRail customer success team. They will produce a response obtained from product resources, containing the App ID and API Key values/credentials generated specifically for your shipper's organization. Each shipper defined for your account will need a set of API credentials that identifies orders associated with a particular shipper. Ensure that requests sent to the Delivery API by your application are utilizing the correct credentials when sending a shipper's order.
These credentials can now be used to authenticate any request intended for your organization's OneRail account. To implement these credentials, their values will need to be added to the header of any request intended for the OneRail API Engine. The following code blocks shows the headers and their associated values:
X-ONERAIL-APP-ID: App ID provided by your implementation manager
X-ONERAIL-API-KEY: API Key provided by your implementation managerOrder & Delivery Functions
Following authentication, your application can send functional requests to the OneRail API Engine on behalf of your organization or user (depending on the method of authentication being utilized). The endpoints below follow the order-first model: you create an order from shipper details, and OneRail generates the deliveries from it.
Check Delivery Availability
Before creating an order or adding a delivery, send the available pickup and drop-off details to POST /delivery/check-availability to confirm whether the delivery can be serviced.
Only pickUpData and dropOffData are required. Each location can contain partial address data, a geopoint, or both. A request with only location data returns top-level availability. A richer request can return service-level availability and an optional estimatedPrice when the API computes one.
Note: Check Availability confirms serviceability; it does not replace rate shopping in the v2 order workflow. To perform rate shopping as part of an order request, set shopRates to true in the POST /v2/order request. The schema default is false.
The schemas below are current as of this article's last update. For the authoritative definitions, refer to the Delivery API Swagger reference.
POST/delivery/check-availabilityCheck delivery availability using progressive input. Minimal requests can return top-level availability only; richer requests can include service-level details.
Parameters
No parameters
Request Bodyrequiredapplication/json
Delivery data for availability check. Only pickUpData and dropOffData are required, and each may contain partial location data.
{
"serviceLevels": [
"string"
],
"notes": "string",
"contractId": "string",
"requestLabel": true,
"labelType": "png",
"carrierLabelType": "string",
"carrierCode": "string",
"carrierServiceName": "string",
"deliveryType": "BUSINESS",
"deliveryOptions": [
"REQUIRE_SIGNATURE"
],
"customerData": {
"firstName": "string",
"lastName": "string",
"phone": "string",
"emailAddress": "string"
},
"orderData": {
"orderId": "string",
"netAmount": 0,
"salesChannelId": "string",
"committedDateTime": "2024-01-01T00:00:00Z",
"shippingChargeCent": 0,
"barCode": "string",
"items": [
{
"id": "string",
"description": "string",
"length": 0,
"width": 0,
"height": 0,
"weight": 0,
"quantity": 0,
"identifier": "string",
"barcodeValue": "string",
"barcodeType": "string",
"complexities": "string",
"priceCent": 0,
"nmfc": "string",
"freightClass": "50",
"hazardousMaterialDetails": {
"identificationNumber": "string",
"properShippingName": "string",
"packagingGroup": "string",
"packagingType": "string",
"hazardClass": "string",
"hazardSubClass": "string",
"technicalName": "string",
"dotLabeling": "string"
},
"doNotRotate": true
}
],
"containers": [
{
"name": "string",
"trackingInfo": {
"type": "string",
"value": "string"
},
"totalWeight": 0,
"shipperContainerId": "string",
"barcodeValue": "string",
"barcodeType": "string",
"shipperExtraData": {},
"items": [
{
"id": "string",
"description": "string",
"length": 0,
"width": 0,
"height": 0,
"weight": 0,
"quantity": 0,
"identifier": "string",
"barcodeValue": "string",
"barcodeType": "string",
"complexities": "string",
"priceCent": 0,
"hsCode": "string",
"countryOfManufacture": "string",
"hazardousMaterialDetails": {
"identificationNumber": "string",
"properShippingName": "string",
"packagingGroup": "string",
"packagingType": "string",
"hazardClass": "string",
"hazardSubClass": "string",
"technicalName": "string",
"dotLabeling": "string"
},
"doNotRotate": true
}
],
"hazardousMaterialDetails": {
"signatoryContactField": "string",
"emergencyContactNumber": "string",
"signatoryContactTitle": "string",
"signatoryContactPlace": "string",
"offeror": "string",
"dotLabeling": "string",
"authorization": "string",
"fedExPackagingType": "string"
},
"subContainerQuantity": 0,
"uniqueSubLabels": true,
"nmfc": "string",
"freightClass": "50"
}
],
"status": "string",
"lpName": "string",
"nmfc": "string",
"freightClass": "50",
"originLocation": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string"
}
},
"pickUpData": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string",
"dueDate": "string",
"windows": {
"opensOn": "string",
"closesOn": "string"
},
"appointment": {
"durationMins": 0,
"description": "string"
},
"physicalLocation": {
"altLocation": {
"latitude": 0,
"longitude": 0
},
"altAddress": "string"
},
"capabilityTags": [
"string"
]
},
"dropOffData": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string",
"dueDate": "string",
"windows": {
"opensOn": "string",
"closesOn": "string"
},
"appointment": {
"durationMins": 0,
"description": "string"
},
"physicalLocation": {
"altLocation": {
"latitude": 0,
"longitude": 0
},
"altAddress": "string"
},
"capabilityTags": [
"string"
]
},
"shipperExtraData": {},
"state": "DRAFT",
"serviceLevel": "string",
"shipmentId": "string",
"contactPreference": "EMAIL",
"dispatchAt": "2024-01-01T00:00:00Z",
"nmfc": "string",
"freightClass": "50",
"numericSystem": "IMPERIAL",
"deliveryFiles": "string",
"emergencyContact": {
"contactName": "string",
"contactTitle": "string",
"phoneNumber": "string",
"email": "string"
},
"deliveryInternationalDetails": {
"ftrExemptionCode": "string",
"aesItn": "string",
"itemCategory": "merchandise",
"itemDescription": "string",
"shippingRestriction": "none",
"restrictionNotes": "string",
"isCustomsCertified": true,
"certifyingParty": "string"
},
"nonDeliveryBehavior": "return"
}| Field | Type | Description |
|---|---|---|
| serviceLevels | Array of strings | Optional service level names to check. |
| notes | string | Delivery Notes |
| contractId | string | The OneRail contract to deliver this package under |
| requestLabel | boolean | Request a shipping label be added to the response. Default false |
| labelType | string |
Format of shipping label generated by Onerail. Represented as a base64-encoded string in the response Enum:
png, pdf, zpl
|
| carrierLabelType | string | Format of shipping label generated by a carrier. |
| carrierCode | string | Code identifying the carrier requested to perform the delivery (e.g., FDEX, UPS). Contact OneRail to obtain a list of valid carrier codes. |
| carrierServiceName | string | Name of the specific carrier service level requested for the delivery. Contact OneRail to obtain a list of valid carrier service names. |
| deliveryType | string |
— Enum:
BUSINESS, RESIDENTIAL
|
| deliveryOptions | Array of strings | — |
| customerData | object | — |
| firstNamerequired | string | — |
| lastNamerequired | string | — |
| phonerequired | string | — |
| emailAddress | string | — |
| orderData | object | Order payload for delivery create. Provide `items` or `containers`, not both. A present array, even empty, counts as that shape. Omitted keys are absent. Runtime validation rejects a request when both keys are present. |
| orderIdrequired | string | The ID of the order from a partner's system |
| netAmount | integer | Order amount (in cents) |
| salesChannelId | string | — |
| committedDateTime | string | — |
| shippingChargeCent | integer | — |
| barCode | string | Bar/QR code for this order |
| items | Array of objects | Top-level order items. Mutually exclusive with containers. |
| id | string | OneRail internal item id. if this id is valid OneRail line item it will be ignored during delivery creation. |
| descriptionrequired | string | Description of this item |
| lengthrequired | number | Length in inches of this item |
| widthrequired | number | Width in inches of this item |
| heightrequired | number | Height in inches of this item |
| weightrequired | number | Weight in pounds (As a floating point number. Fractional pounds are ok) |
| quantityrequired | integer | The number of this same item included with the order |
| identifier | string | Product SKU, ID, or UPC |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| complexities | string | — |
| priceCent | integer | Order amount (in cents) |
| nmfc | string | The national motor freight code for this order item. |
| freightClass | string |
The freight class for this order item. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| hazardousMaterialDetails | object | — |
| identificationNumber | string | Number to identify hazard as designated by shipper (example UN or NP numbers) |
| properShippingName | string | The proper shipping name identified by the Shipping Table as desingnated by the shipper |
| packagingGroup | string | designation for the group of packages provided by the shipper |
| packagingType | string | The type of package holding the hazardous material as designated by the shipper |
| hazardClass | string | Value from the hazard classification system |
| hazardSubClass | string | Value from the hazard classification system for the sub class |
| technicalName | string | Technical description given by the shipper for the hazardous item |
| dotLabeling | string | Type of label to be placed on the items |
| doNotRotate | boolean | — |
| containers | Array of objects | — |
| namerequired | string | — |
| trackingInfo | object | — |
| type | string | — |
| value | string | — |
| totalWeightrequired | number | Weight of container and all items inside it |
| shipperContainerId | string | — |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| shipperExtraData | object | Any additional shipping data in JSON format |
| itemsrequired | Array of objects | — |
| id | string | OneRail internal item id. if this id is valid OneRail line item it will be ignored during delivery creation. |
| descriptionrequired | string | Description of this item |
| lengthrequired | number | Length in inches of this item |
| widthrequired | number | Width in inches of this item |
| heightrequired | number | Height in inches of this item |
| weightrequired | number | Weight in pounds (As a floating point number. Fractional pounds are ok) |
| quantityrequired | integer | The number of this same item included with the order |
| identifier | string | Product SKU, ID, or UPC |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| complexities | string | — |
| priceCent | integer | Order amount (in cents) |
| hsCode | string | Harmonized System (HS) code for classifying goods. |
| countryOfManufacture | string | The country code where the item was manufactured |
| hazardousMaterialDetails | object | — |
| identificationNumber | string | Number to identify hazard as designated by shipper (example UN or NP numbers) |
| properShippingName | string | The proper shipping name identified by the Shipping Table as desingnated by the shipper |
| packagingGroup | string | designation for the group of packages provided by the shipper |
| packagingType | string | The type of package holding the hazardous material as designated by the shipper |
| hazardClass | string | Value from the hazard classification system |
| hazardSubClass | string | Value from the hazard classification system for the sub class |
| technicalName | string | Technical description given by the shipper for the hazardous item |
| dotLabeling | string | Type of label to be placed on the items |
| doNotRotate | boolean | — |
| hazardousMaterialDetails | object | — |
| signatoryContactField | string | Person responsible for hazmat shipment compliance |
| emergencyContactNumber | string | Phone number of emergency contact for hazmat shipment |
| signatoryContactTitle | string | Professional title of person responsible for the hazmat shipment compliance |
| signatoryContactPlace | string | Organization (company) name or code |
| offeror | string | Organization (company) name or code |
| dotLabeling | string | Type of label to be placed on the container |
| authorization | string | Part of DOT Labeling |
| fedExPackagingType | string | Type of packaging type to be applied for fedex |
| subContainerQuantity | number | — |
| uniqueSubLabels | boolean | — |
| nmfc | string | The national motor freight code for this container. |
| freightClass | string |
The freight class for this container. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| status | string | — |
| lpName | string | — |
| nmfc | string | The national motor freight code for this order item. |
| freightClass | string |
The freight class for this order item. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| originLocation | object | — |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1required | string | — |
| address2 | string | — |
| cityrequired | string | — |
| staterequired | string | — |
| country | string | — |
| ziprequired | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| pickUpDatarequired | object | Pickup location data. Provide any combination of address fields, a geopoint, or both. |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1 | string | — |
| address2 | string | — |
| city | string | — |
| state | string | — |
| country | string | — |
| zip | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| dueDate | string | Indicates when this location should be fulfilled by. Time format iso-8601 |
| windows | object | — |
| opensOn | string | Open window datetime in format iso-8601 |
| closesOn | string | Close window datetime in format iso-8601 |
| appointment | object | — |
| durationMins | number | The duration time in minutes (integer) |
| description | string | The description of the appointment |
| physicalLocation | object | — |
| altLocation | object | — |
| latitude | number | — |
| longitude | number | — |
| altAddress | alt-address.yaml | — |
| capabilityTags | Array of objects | — |
| dropOffDatarequired | object | Drop-off location data. Provide any combination of address fields, a geopoint, or both. |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1 | string | — |
| address2 | string | — |
| city | string | — |
| state | string | — |
| country | string | — |
| zip | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| dueDate | string | Indicates when this location should be fulfilled by. Time format iso-8601 |
| windows | object | — |
| opensOn | string | Open window datetime in format iso-8601 |
| closesOn | string | Close window datetime in format iso-8601 |
| appointment | object | — |
| durationMins | number | The duration time in minutes (integer) |
| description | string | The description of the appointment |
| physicalLocation | object | — |
| altLocation | object | — |
| latitude | number | — |
| longitude | number | — |
| altAddress | alt-address.yaml | — |
| capabilityTags | Array of objects | — |
| shipperExtraData | object | JSON blob that the customer can use to store additional info they may need. |
| state | string |
— Enum:
DRAFT, READY_TO_DISPATCH
|
| serviceLevel | string | — |
| shipmentId | string | — |
| contactPreference | string |
— Enum:
EMAIL, SMS, BOTH, None
|
| dispatchAt | string | datetime in ISO format |
| nmfc | string | The national motor freight code for this delivery. This is a convenience function to set the same NMFC code for all the containers or order items in this delivery. |
| freightClass | string |
The freight class for this delivery. This is a convenience function to set the same freight class for all the containers or order items in this delivery. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| numericSystem | string |
— Enum:
IMPERIAL, METRIC
|
| deliveryFiles | record.yaml | — |
| emergencyContact | object | — |
| contactName | string | Emergency contact name |
| contactTitle | string | Emergency contact title |
| phoneNumber | string | Emergency contact phone number |
| string | Emergency contact email | |
| deliveryInternationalDetails | object | Export compliance information used for international shipments. Only one of the fields should be provided depending on the regulatory requirements: - If EEI filing in AES is required → provide `aesItn` - If EEI filing is not required → provide `ftrExemption` |
| ftrExemptionCode | string | FTR Exemption Statement indicating why EEI filing in AES is not required. Example: 'NO EEI 30.37(a)' |
| aesItn | string | Automated Export System Internal Transaction Number (ITN) returned after EEI submission. Format: 'AES X20250427123456' |
| itemCategory | string |
Represents a classification/type of items. Enum:
merchandise, returned_goods, documents, gift, sample, other
|
| itemDescription | string | A free-text explanation of what the contents are (only applicable if "itemCategory" is "other"). |
| shippingRestriction | string |
Represents any type of limitation (e.g., hazardous, embargoed). Enum:
none, other, quarantine, sanitary_phytosanitary_inspection
|
| restrictionNotes | string | Free-text comments clarifying or explaining the restriction (only applicable if "shippingRestriction" is not "none"). |
| isCustomsCertified | boolean | Boolean flag indicating certification status. |
| certifyingParty | string | Name of the person or entity signing the customs form. |
| nonDeliveryBehavior | string |
Specifies the action to take if the shipment cannot be delivered. Accepted values are: - `return`: The package will be returned to the sender. - `abandon`: The package will not be returned and may be discarded or handled at the carrier's discretion. Enum:
return, abandon
|
Responses
| Code | Description | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 |
Availability result for the supplied delivery data
|
|||||||||||||||||||||||||||||||||||||||
| 400 |
Unexpected error
|
Creating an Order
The POST /v2/order endpoint creates orders and their associated deliveries. The request body requires orderAction, orderData, and deliveries.
Set orderAction to CREATE when creating a new order. The partner-defined orderData.orderId must be unique. Deliveries can be created and associated in the same request as the order.
Set shopRates to true when rate shopping is needed as part of the order request. The field is a boolean and defaults to false. When rate shopping is requested, review the response rates array for the rates associated with the created deliveries.
For bundled parcel orders, send each Bundle as its own delivery so it can be processed independently and receive its own master tracking number. Include all Bundles and individual Cartons in the order before the order reaches READY_TO_DISPATCH. For a Bundle, send the summed weight and dimensions for the entire Bundle.
Upon successful processing, the response will provide the UUIDs for both the order and each of the deliveries created from it. These UUIDs can be used to reference and track the order and its associated deliveries in subsequent requests.
POST/v2/orderCreate an order with deliveries and returns
Parameters
No parameters
Request Bodyrequiredapplication/json
Order Info and its deliveries
to get accessorials you should pass it in:
deliveries -> dropOffData -> capabilityTags or deliveries -> pickUpData -> capabilityTags
in request body as one of the these schemas:
1 => array of capabilityTags ids ['043e7f08-10f7-4c13-bfb1-76eaf96e4a24'];
2 => array of capabilityTags names ['Pup'];
3 => array of name and quantity object [{ name : 'Pup', quantity : 20 }];
4 => array of id and quantity object [{ id : '043e7f08-10f7-4c13-bfb1-76eaf96e4a24', quantity : 20 }]
to get accessorials you should pass it in:
deliveries -> dropOffData -> capabilityTags or deliveries -> pickUpData -> capabilityTags
in request body as one of the these schemas:
1 => array of capabilityTags ids ['043e7f08-10f7-4c13-bfb1-76eaf96e4a24'];
2 => array of capabilityTags names ['Pup'];
3 => array of name and quantity object [{ name : 'Pup', quantity : 20 }];
4 => array of id and quantity object [{ id : '043e7f08-10f7-4c13-bfb1-76eaf96e4a24', quantity : 20 }]
{
"orderAction": "CREATE",
"state": "DRAFT",
"serviceLevel": "string",
"deliveryOptions": [
"REQUIRE_SIGNATURE"
],
"orderData": {
"orderId": "string",
"contractId": "string",
"netAmount": 0,
"salesChannelId": "00000000-0000-0000-0000-000000000000",
"committedDateTime": "2026-10-09T12:00:00Z",
"orderDateTime": "2026-10-09T12:00:00Z",
"shippingChargeCent": 0,
"barCode": "string",
"status": "string",
"nmfc": "string",
"freightClass": "50",
"originLocation": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string"
}
},
"deliveries": [
{
"labelType": "string",
"requestLabel": true,
"barcodeVerificationRequired": "string",
"carrierLabelType": "string",
"carrierCode": "string",
"carrierServiceName": "string",
"shipmentId": "string",
"notes": "string",
"contactPreference": "EMAIL",
"deliveryType": "BUSINESS",
"pickUpData": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string",
"dueDate": "string",
"windows": {
"opensOn": "string",
"closesOn": "string"
},
"appointment": {
"durationMins": 0,
"description": "string"
},
"physicalLocation": {
"altLocation": {
"latitude": 0,
"longitude": 0
},
"altAddress": "string"
},
"capabilityTags": [
"string"
]
},
"dropOffData": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string",
"dueDate": "string",
"windows": {
"opensOn": "string",
"closesOn": "string"
},
"appointment": {
"durationMins": 0,
"description": "string"
},
"physicalLocation": {
"altLocation": {
"latitude": 0,
"longitude": 0
},
"altAddress": "string"
},
"capabilityTags": [
"string"
]
},
"items": [
{
"id": "string",
"description": "string",
"length": 0,
"width": 0,
"height": 0,
"weight": 0,
"quantity": 0,
"identifier": "string",
"barcodeValue": "string",
"barcodeType": "string",
"complexities": "string",
"priceCent": 0,
"nmfc": "string",
"freightClass": "50",
"hazardousMaterialDetails": {
"identificationNumber": "string",
"properShippingName": "string",
"packagingGroup": "string",
"packagingType": "string",
"hazardClass": "string",
"hazardSubClass": "string",
"technicalName": "string",
"dotLabeling": "string"
},
"doNotRotate": true
}
],
"containers": [
{
"name": "string",
"trackingInfo": {
"type": "string",
"value": "string"
},
"totalWeight": 0,
"shipperContainerId": "string",
"barcodeValue": "string",
"barcodeType": "string",
"shipperExtraData": {},
"items": [
{
"id": "string",
"description": "string",
"length": 0,
"width": 0,
"height": 0,
"weight": 0,
"quantity": 0,
"identifier": "string",
"barcodeValue": "string",
"barcodeType": "string",
"complexities": "string",
"priceCent": 0,
"hsCode": "string",
"countryOfManufacture": "string",
"hazardousMaterialDetails": {
"identificationNumber": "string",
"properShippingName": "string",
"packagingGroup": "string",
"packagingType": "string",
"hazardClass": "string",
"hazardSubClass": "string",
"technicalName": "string",
"dotLabeling": "string"
},
"doNotRotate": true
}
],
"hazardousMaterialDetails": {
"signatoryContactField": "string",
"emergencyContactNumber": "string",
"signatoryContactTitle": "string",
"signatoryContactPlace": "string",
"offeror": "string",
"dotLabeling": "string",
"authorization": "string",
"fedExPackagingType": "string"
},
"subContainerQuantity": 0,
"uniqueSubLabels": true,
"nmfc": "string",
"freightClass": "50"
}
],
"shipperExtraData": {},
"dispatchAt": "2024-01-01T00:00:00Z",
"nmfc": "string",
"freightClass": "50",
"deliveryFiles": "string",
"emergencyContact": {
"contactName": "string",
"contactTitle": "string",
"phoneNumber": "string",
"email": "string"
},
"deliveryInternationalDetails": {
"ftrExemptionCode": "string",
"aesItn": "string",
"itemCategory": "merchandise",
"itemDescription": "string",
"shippingRestriction": "none",
"restrictionNotes": "string",
"isCustomsCertified": true,
"certifyingParty": "string"
},
"nonDeliveryBehavior": "return",
"parentId": "string",
"requestedFleetVehicle": {
"id": "string",
"name": "string"
},
"requestedFleetVehicleId": "string"
}
],
"numericSystem": "IMPERIAL",
"capabilityTags": [
"string"
],
"shopRates": true
}| Field | Type | Description |
|---|---|---|
| orderActionrequired | string |
Determines whether the request creates an order, adds deliveries, or creates returns. Enum:
CREATE, ADD, RETURN
|
| state | string |
— Enum:
DRAFT, READY_TO_DISPATCH
|
| serviceLevel | string | — |
| deliveryOptions | Array of strings | — |
| orderData | object | — |
| orderId | string | The ID of the order from a partner's system |
| contractId | string | The OneRail contract to deliver this package under |
| netAmount | integer | Order amount (in cents) |
| salesChannelId | string | Optional sales channel UUID. |
| committedDateTime | string | Optional date-time with Z or a UTC offset. |
| orderDateTime | string | Optional date-time with Z or a UTC offset. |
| shippingChargeCent | integer | Optional shipping charge in cents; minimum 0. |
| barCode | string | Bar/QR code for this order |
| status | string | — |
| nmfc | string | The national motor freight code for this order item. |
| freightClass | string |
The freight class for this order item. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| originLocation | object | — |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1required | string | — |
| address2 | string | — |
| cityrequired | string | — |
| staterequired | string | — |
| country | string | — |
| ziprequired | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| deliveries | Array of objects | — |
| labelType | string | The type of label to print on the delivery |
| requestLabel | boolean | Indicates if a label should be requested for this delivery |
| barcodeVerificationRequired | verification-required.yaml | — |
| carrierLabelType | string | Format of shipping label generated by a carrier. |
| carrierCode | string | Code identifying the carrier requested to perform the delivery (e.g., FDEX, UPS). Contact OneRail to obtain a list of valid carrier codes. |
| carrierServiceName | string | Name of the specific carrier service level requested for the delivery. Contact OneRail to obtain a list of valid carrier service names. |
| shipmentId | string | Shipment ID |
| notes | string | Delivery Notes |
| contactPreference | string |
— Enum:
EMAIL, SMS, BOTH, None
|
| deliveryTyperequired | string |
— Enum:
BUSINESS, RESIDENTIAL
|
| pickUpDatarequired | object | — |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1required | string | — |
| address2 | string | — |
| cityrequired | string | — |
| staterequired | string | — |
| country | string | — |
| ziprequired | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| dueDate | string | Indicates when this location should be fulfilled by. Time format iso-8601 |
| windows | object | — |
| opensOn | string | Open window datetime in format iso-8601 |
| closesOn | string | Close window datetime in format iso-8601 |
| appointment | object | — |
| durationMins | number | The duration time in minutes (integer) |
| description | string | The description of the appointment |
| physicalLocation | object | — |
| altLocation | object | — |
| latitude | number | — |
| longitude | number | — |
| altAddress | alt-address.yaml | — |
| capabilityTags | Array of objects | — |
| dropOffDatarequired | object | — |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1required | string | — |
| address2 | string | — |
| cityrequired | string | — |
| staterequired | string | — |
| country | string | — |
| ziprequired | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| dueDate | string | Indicates when this location should be fulfilled by. Time format iso-8601 |
| windows | object | — |
| opensOn | string | Open window datetime in format iso-8601 |
| closesOn | string | Close window datetime in format iso-8601 |
| appointment | object | — |
| durationMins | number | The duration time in minutes (integer) |
| description | string | The description of the appointment |
| physicalLocation | object | — |
| altLocation | object | — |
| latitude | number | — |
| longitude | number | — |
| altAddress | alt-address.yaml | — |
| capabilityTags | Array of objects | — |
| items | Array of objects | — |
| id | string | OneRail internal item id. if this id is valid OneRail line item it will be ignored during delivery creation. |
| descriptionrequired | string | Description of this item |
| lengthrequired | number | Length in inches of this item |
| widthrequired | number | Width in inches of this item |
| heightrequired | number | Height in inches of this item |
| weightrequired | number | Weight in pounds (As a floating point number. Fractional pounds are ok) |
| quantityrequired | integer | The number of this same item included with the order |
| identifier | string | Product SKU, ID, or UPC |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| complexities | string | — |
| priceCent | integer | Order amount (in cents) |
| nmfc | string | The national motor freight code for this order item. |
| freightClass | string |
The freight class for this order item. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| hazardousMaterialDetails | object | — |
| identificationNumber | string | Number to identify hazard as designated by shipper (example UN or NP numbers) |
| properShippingName | string | The proper shipping name identified by the Shipping Table as desingnated by the shipper |
| packagingGroup | string | designation for the group of packages provided by the shipper |
| packagingType | string | The type of package holding the hazardous material as designated by the shipper |
| hazardClass | string | Value from the hazard classification system |
| hazardSubClass | string | Value from the hazard classification system for the sub class |
| technicalName | string | Technical description given by the shipper for the hazardous item |
| dotLabeling | string | Type of label to be placed on the items |
| doNotRotate | boolean | — |
| containers | Array of objects | — |
| namerequired | string | — |
| trackingInfo | object | — |
| type | string | — |
| value | string | — |
| totalWeightrequired | number | Weight of container and all items inside it |
| shipperContainerId | string | — |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| shipperExtraData | object | Any additional shipping data in JSON format |
| itemsrequired | Array of objects | — |
| id | string | OneRail internal item id. if this id is valid OneRail line item it will be ignored during delivery creation. |
| descriptionrequired | string | Description of this item |
| lengthrequired | number | Length in inches of this item |
| widthrequired | number | Width in inches of this item |
| heightrequired | number | Height in inches of this item |
| weightrequired | number | Weight in pounds (As a floating point number. Fractional pounds are ok) |
| quantityrequired | integer | The number of this same item included with the order |
| identifier | string | Product SKU, ID, or UPC |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| complexities | string | — |
| priceCent | integer | Order amount (in cents) |
| hsCode | string | Harmonized System (HS) code for classifying goods. |
| countryOfManufacture | string | The country code where the item was manufactured |
| hazardousMaterialDetails | object | — |
| identificationNumber | string | Number to identify hazard as designated by shipper (example UN or NP numbers) |
| properShippingName | string | The proper shipping name identified by the Shipping Table as desingnated by the shipper |
| packagingGroup | string | designation for the group of packages provided by the shipper |
| packagingType | string | The type of package holding the hazardous material as designated by the shipper |
| hazardClass | string | Value from the hazard classification system |
| hazardSubClass | string | Value from the hazard classification system for the sub class |
| technicalName | string | Technical description given by the shipper for the hazardous item |
| dotLabeling | string | Type of label to be placed on the items |
| doNotRotate | boolean | — |
| hazardousMaterialDetails | object | — |
| signatoryContactField | string | Person responsible for hazmat shipment compliance |
| emergencyContactNumber | string | Phone number of emergency contact for hazmat shipment |
| signatoryContactTitle | string | Professional title of person responsible for the hazmat shipment compliance |
| signatoryContactPlace | string | Organization (company) name or code |
| offeror | string | Organization (company) name or code |
| dotLabeling | string | Type of label to be placed on the container |
| authorization | string | Part of DOT Labeling |
| fedExPackagingType | string | Type of packaging type to be applied for fedex |
| subContainerQuantity | number | — |
| uniqueSubLabels | boolean | — |
| nmfc | string | The national motor freight code for this container. |
| freightClass | string |
The freight class for this container. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| shipperExtraData | object | — |
| dispatchAt | string | datetime in ISO format |
| nmfc | string | The national motor freight code for this order. This is a convenience function to set the same NMFC code for all the containers or order items of all the deliveries in this order. |
| freightClass | string |
The freight class for this order. This is a convenience function to set the same freight class for all the containers or order items of all the deliveries in this order. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| deliveryFiles | record.yaml | — |
| emergencyContact | object | — |
| contactName | string | Emergency contact name |
| contactTitle | string | Emergency contact title |
| phoneNumber | string | Emergency contact phone number |
| string | Emergency contact email | |
| deliveryInternationalDetails | object | Export compliance information used for international shipments. Only one of the fields should be provided depending on the regulatory requirements: - If EEI filing in AES is required → provide `aesItn` - If EEI filing is not required → provide `ftrExemption` |
| ftrExemptionCode | string | FTR Exemption Statement indicating why EEI filing in AES is not required. Example: 'NO EEI 30.37(a)' |
| aesItn | string | Automated Export System Internal Transaction Number (ITN) returned after EEI submission. Format: 'AES X20250427123456' |
| itemCategory | string |
Represents a classification/type of items. Enum:
merchandise, returned_goods, documents, gift, sample, other
|
| itemDescription | string | A free-text explanation of what the contents are (only applicable if "itemCategory" is "other"). |
| shippingRestriction | string |
Represents any type of limitation (e.g., hazardous, embargoed). Enum:
none, other, quarantine, sanitary_phytosanitary_inspection
|
| restrictionNotes | string | Free-text comments clarifying or explaining the restriction (only applicable if "shippingRestriction" is not "none"). |
| isCustomsCertified | boolean | Boolean flag indicating certification status. |
| certifyingParty | string | Name of the person or entity signing the customs form. |
| nonDeliveryBehavior | string |
Specifies the action to take if the shipment cannot be delivered. Accepted values are: - `return`: The package will be returned to the sender. - `abandon`: The package will not be returned and may be discarded or handled at the carrier's discretion. Enum:
return, abandon
|
| parentId | string | The return delivery's parent deliveryId, required for return deliveries |
| requestedFleetVehicle | object | Client-requested fleet vehicle. Send unique FleetVehicle.name or id. Omit, null, empty object, or empty-string id/name supplies no foreign key. Operations persists suggestedFleetVehicleId. Unknown non-blank names are rejected. |
| id | string | Optional FleetVehicle UUID. Omit, null, or empty string supplies no foreign key. |
| name | string | Unique FleetVehicle.name. Omit, null, or empty/whitespace string supplies no foreign key. |
| requestedFleetVehicleId | string | Optional FleetVehicle UUID. Omit, null, or empty string supplies no foreign key. |
| numericSystem | string |
— Enum:
IMPERIAL, METRIC
|
| capabilityTags | Array of objects | — |
| shopRates | boolean | Wait for delivery calculations to complete before returning the response. |
Responses
| Code | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 |
Success. The order and deliveries have been created
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 422 |
Unexpected error
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| default |
Unexpected error
|
Order Partial Update
The function of this endpoint provides a partial update to the details of a specifically requested order. This functionality can also add or replace items and containers to an existing order (if that update is needed).
Note: This endpoint cannot be used after an order has been dispatched. Ensure any partial updates are submitted prior to dispatch.
This endpoint will append items and containers to an existing order when requests are made with the PATCH request method. This endpoint will replace items and containers for an existing order when requests are made with the PUT request method.
For further details regarding this endpoint, refer to the following Swagger reference:
PATCH/order/{orderId}/partial-updatePartial update an order with deliveries, appending items and containers
Parameters
| Name | Type | Description |
|---|---|---|
| orderIdrequired | string(path) | order Id |
Request Bodyoptionalapplication/json
Order Info and its deliveries
{
"notes": "string",
"contractId": "00000000-0000-0000-0000-000000000000",
"requestLabel": true,
"requestIndividualLabels": true,
"labelType": "png",
"carrierLabelType": "string",
"carrierCode": "string",
"carrierServiceName": "string",
"deliveryType": "BUSINESS",
"deliveryOptions": [
"REQUIRE_SIGNATURE"
],
"customerData": {
"firstName": "string",
"lastName": "string",
"phone": "string",
"emailAddress": "string"
},
"orderData": {
"orderId": "string",
"netAmount": 0,
"salesChannelId": "00000000-0000-0000-0000-000000000000",
"committedDateTime": "2026-10-09T12:00:00Z",
"shippingChargeCent": 0,
"barCode": "string",
"items": [
{
"id": "string",
"description": "string",
"length": 0,
"width": 0,
"height": 0,
"weight": 0,
"quantity": 0,
"identifier": "string",
"barcodeValue": "string",
"barcodeType": "string",
"complexities": "string",
"priceCent": 0,
"nmfc": "string",
"freightClass": "50",
"hazardousMaterialDetails": {
"identificationNumber": "string",
"properShippingName": "string",
"packagingGroup": "string",
"packagingType": "string",
"hazardClass": "string",
"hazardSubClass": "string",
"technicalName": "string",
"dotLabeling": "string"
},
"doNotRotate": true
}
],
"containers": [
{
"name": "string",
"trackingInfo": {
"type": "string",
"value": "string"
},
"totalWeight": 0,
"shipperContainerId": "string",
"barcodeValue": "string",
"barcodeType": "string",
"shipperExtraData": {},
"items": [
{
"id": "string",
"description": "string",
"length": 0,
"width": 0,
"height": 0,
"weight": 0,
"quantity": 0,
"identifier": "string",
"barcodeValue": "string",
"barcodeType": "string",
"complexities": "string",
"priceCent": 0,
"hsCode": "string",
"countryOfManufacture": "string",
"hazardousMaterialDetails": {
"identificationNumber": "string",
"properShippingName": "string",
"packagingGroup": "string",
"packagingType": "string",
"hazardClass": "string",
"hazardSubClass": "string",
"technicalName": "string",
"dotLabeling": "string"
},
"doNotRotate": true
}
],
"hazardousMaterialDetails": {
"signatoryContactField": "string",
"emergencyContactNumber": "string",
"signatoryContactTitle": "string",
"signatoryContactPlace": "string",
"offeror": "string",
"dotLabeling": "string",
"authorization": "string",
"fedExPackagingType": "string"
},
"subContainerQuantity": 0,
"uniqueSubLabels": true,
"nmfc": "string",
"freightClass": "50"
}
],
"status": "string",
"lpName": "string",
"nmfc": "string",
"freightClass": "50",
"originLocation": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string"
}
},
"pickUpData": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string",
"dueDate": "string",
"windows": {
"opensOn": "string",
"closesOn": "string"
},
"appointment": {
"durationMins": 0,
"description": "string"
},
"physicalLocation": {
"altLocation": {
"latitude": 0,
"longitude": 0
},
"altAddress": "string"
},
"capabilityTags": [
"string"
]
},
"dropOffData": {
"name": "string",
"storeNumber": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string",
"instructions": "string",
"code": "string",
"contactName": "string",
"contactPhone": "string",
"contactEmailAddress": "string",
"dueDate": "string",
"windows": {
"opensOn": "string",
"closesOn": "string"
},
"appointment": {
"durationMins": 0,
"description": "string"
},
"physicalLocation": {
"altLocation": {
"latitude": 0,
"longitude": 0
},
"altAddress": "string"
},
"capabilityTags": [
"string"
]
},
"emergencyContact": {
"contactName": "string",
"contactTitle": "string",
"phoneNumber": "string",
"email": "string"
},
"shipperExtraData": {},
"state": "DRAFT",
"serviceLevel": "string",
"shipmentId": "string",
"lpName": "string",
"contactPreference": "EMAIL",
"nmfc": "string",
"freightClass": "50",
"numericSystem": "IMPERIAL",
"deliveryFiles": "string",
"deliveryInternationalDetails": {
"ftrExemptionCode": "string",
"aesItn": "string",
"itemCategory": "merchandise",
"itemDescription": "string",
"shippingRestriction": "none",
"restrictionNotes": "string",
"isCustomsCertified": true,
"certifyingParty": "string"
},
"nonDeliveryBehavior": "return"
}| Field | Type | Description |
|---|---|---|
| notes | string | Delivery Notes |
| contractId | string | The OneRail contract to deliver this package under |
| requestLabel | boolean | Request a shipping label be added to the response. |
| requestIndividualLabels | boolean | Request a shipping label be added to the response, with subcontainer labels broken out into separate items. |
| labelType | string |
Format of shipping label if requested. Represented as a base64-encoded string in the response if requested. Enum:
png, pdf, zpl
|
| carrierLabelType | string | Format of shipping label generated by a carrier. |
| carrierCode | string | Code identifying the carrier requested to perform the delivery (e.g., FDEX, UPS). Contact OneRail to obtain a list of valid carrier codes. |
| carrierServiceName | string | Name of the specific carrier service level requested for the delivery. Contact OneRail to obtain a list of valid carrier service names. |
| deliveryType | string |
Type of delivery Enum:
BUSINESS, RESIDENTIAL
|
| deliveryOptions | Array of strings | Optional delivery requirements |
| customerData | object | Pickup contact |
| firstNamerequired | string | — |
| lastNamerequired | string | — |
| phonerequired | string | — |
| emailAddress | string | — |
| orderData | object | Order payload for delivery create. Provide `items` or `containers`, not both. A present array, even empty, counts as that shape. Omitted keys are absent. Runtime validation rejects a request when both keys are present. |
| orderIdrequired | string | The ID of the order from a partner's system |
| netAmount | integer | Order amount (in cents) |
| salesChannelId | string | — |
| committedDateTime | string | — |
| shippingChargeCent | integer | — |
| barCode | string | Bar/QR code for this order |
| items | Array of objects | Top-level order items. Mutually exclusive with containers. |
| id | string | OneRail internal item id. if this id is valid OneRail line item it will be ignored during delivery creation. |
| descriptionrequired | string | Description of this item |
| lengthrequired | number | Length in inches of this item |
| widthrequired | number | Width in inches of this item |
| heightrequired | number | Height in inches of this item |
| weightrequired | number | Weight in pounds (As a floating point number. Fractional pounds are ok) |
| quantityrequired | integer | The number of this same item included with the order |
| identifier | string | Product SKU, ID, or UPC |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| complexities | string | — |
| priceCent | integer | Order amount (in cents) |
| nmfc | string | The national motor freight code for this order item. |
| freightClass | string |
The freight class for this order item. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| hazardousMaterialDetails | object | — |
| identificationNumber | string | Number to identify hazard as designated by shipper (example UN or NP numbers) |
| properShippingName | string | The proper shipping name identified by the Shipping Table as desingnated by the shipper |
| packagingGroup | string | designation for the group of packages provided by the shipper |
| packagingType | string | The type of package holding the hazardous material as designated by the shipper |
| hazardClass | string | Value from the hazard classification system |
| hazardSubClass | string | Value from the hazard classification system for the sub class |
| technicalName | string | Technical description given by the shipper for the hazardous item |
| dotLabeling | string | Type of label to be placed on the items |
| doNotRotate | boolean | — |
| containers | Array of objects | — |
| namerequired | string | — |
| trackingInfo | object | — |
| type | string | — |
| value | string | — |
| totalWeightrequired | number | Weight of container and all items inside it |
| shipperContainerId | string | — |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| shipperExtraData | object | Any additional shipping data in JSON format |
| itemsrequired | Array of objects | — |
| id | string | OneRail internal item id. if this id is valid OneRail line item it will be ignored during delivery creation. |
| descriptionrequired | string | Description of this item |
| lengthrequired | number | Length in inches of this item |
| widthrequired | number | Width in inches of this item |
| heightrequired | number | Height in inches of this item |
| weightrequired | number | Weight in pounds (As a floating point number. Fractional pounds are ok) |
| quantityrequired | integer | The number of this same item included with the order |
| identifier | string | Product SKU, ID, or UPC |
| barcodeValue | value.yaml | — |
| barcodeType | type.yaml | — |
| complexities | string | — |
| priceCent | integer | Order amount (in cents) |
| hsCode | string | Harmonized System (HS) code for classifying goods. |
| countryOfManufacture | string | The country code where the item was manufactured |
| hazardousMaterialDetails | object | — |
| identificationNumber | string | Number to identify hazard as designated by shipper (example UN or NP numbers) |
| properShippingName | string | The proper shipping name identified by the Shipping Table as desingnated by the shipper |
| packagingGroup | string | designation for the group of packages provided by the shipper |
| packagingType | string | The type of package holding the hazardous material as designated by the shipper |
| hazardClass | string | Value from the hazard classification system |
| hazardSubClass | string | Value from the hazard classification system for the sub class |
| technicalName | string | Technical description given by the shipper for the hazardous item |
| dotLabeling | string | Type of label to be placed on the items |
| doNotRotate | boolean | — |
| hazardousMaterialDetails | object | — |
| signatoryContactField | string | Person responsible for hazmat shipment compliance |
| emergencyContactNumber | string | Phone number of emergency contact for hazmat shipment |
| signatoryContactTitle | string | Professional title of person responsible for the hazmat shipment compliance |
| signatoryContactPlace | string | Organization (company) name or code |
| offeror | string | Organization (company) name or code |
| dotLabeling | string | Type of label to be placed on the container |
| authorization | string | Part of DOT Labeling |
| fedExPackagingType | string | Type of packaging type to be applied for fedex |
| subContainerQuantity | number | — |
| uniqueSubLabels | boolean | — |
| nmfc | string | The national motor freight code for this container. |
| freightClass | string |
The freight class for this container. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| status | string | — |
| lpName | string | — |
| nmfc | string | The national motor freight code for this order item. |
| freightClass | string |
The freight class for this order item. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| originLocation | object | — |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1required | string | — |
| address2 | string | — |
| cityrequired | string | — |
| staterequired | string | — |
| country | string | — |
| ziprequired | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| pickUpData | object | — |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1required | string | — |
| address2 | string | — |
| cityrequired | string | — |
| staterequired | string | — |
| country | string | — |
| ziprequired | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| dueDate | string | Indicates when this location should be fulfilled by. Time format iso-8601 |
| windows | object | — |
| opensOn | string | Open window datetime in format iso-8601 |
| closesOn | string | Close window datetime in format iso-8601 |
| appointment | object | — |
| durationMins | number | The duration time in minutes (integer) |
| description | string | The description of the appointment |
| physicalLocation | object | — |
| altLocation | object | — |
| latitude | number | — |
| longitude | number | — |
| altAddress | alt-address.yaml | — |
| capabilityTags | Array of objects | — |
| dropOffData | object | — |
| name | string | The name of the location |
| storeNumber | string | Store number or store identifier |
| address1required | string | — |
| address2 | string | — |
| cityrequired | string | — |
| staterequired | string | — |
| country | string | — |
| ziprequired | string | Zip Code or Postal Code |
| instructions | string | Instructions for a pickup or delivery |
| code | string | Gate code or other code required to access location |
| contactName | string | Person to contact at the location for pickup or dropoff |
| contactPhone | string | Phone number for the contact at the location |
| contactEmailAddress | string | Email address for the contact at the location |
| dueDate | string | Indicates when this location should be fulfilled by. Time format iso-8601 |
| windows | object | — |
| opensOn | string | Open window datetime in format iso-8601 |
| closesOn | string | Close window datetime in format iso-8601 |
| appointment | object | — |
| durationMins | number | The duration time in minutes (integer) |
| description | string | The description of the appointment |
| physicalLocation | object | — |
| altLocation | object | — |
| latitude | number | — |
| longitude | number | — |
| altAddress | alt-address.yaml | — |
| capabilityTags | Array of objects | — |
| emergencyContact | object | — |
| contactName | string | Emergency contact name |
| contactTitle | string | Emergency contact title |
| phoneNumber | string | Emergency contact phone number |
| string | Emergency contact email | |
| shipperExtraData | object | Any additional shipping data in JSON format |
| state | string |
State of delivery Enum:
DRAFT, READY_TO_DISPATCH
|
| serviceLevel | string | — |
| shipmentId | string | — |
| lpName | string | — |
| contactPreference | string |
— Enum:
EMAIL, SMS, BOTH
|
| nmfc | string | The national motor freight code for this order. This is a convenience function to set the same NMFC code for all the containers or order items of all the deliveries in this order. |
| freightClass | string |
The freight class for this order. This is a convenience function to set the same freight class for all the containers or order items of all the deliveries in this order. Enum:
50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500, None
|
| numericSystem | string |
— Enum:
IMPERIAL, METRIC
|
| deliveryFiles | record.yaml | — |
| deliveryInternationalDetails | object | Export compliance information used for international shipments. Only one of the fields should be provided depending on the regulatory requirements: - If EEI filing in AES is required → provide `aesItn` - If EEI filing is not required → provide `ftrExemption` |
| ftrExemptionCode | string | FTR Exemption Statement indicating why EEI filing in AES is not required. Example: 'NO EEI 30.37(a)' |
| aesItn | string | Automated Export System Internal Transaction Number (ITN) returned after EEI submission. Format: 'AES X20250427123456' |
| itemCategory | string |
Represents a classification/type of items. Enum:
merchandise, returned_goods, documents, gift, sample, other
|
| itemDescription | string | A free-text explanation of what the contents are (only applicable if "itemCategory" is "other"). |
| shippingRestriction | string |
Represents any type of limitation (e.g., hazardous, embargoed). Enum:
none, other, quarantine, sanitary_phytosanitary_inspection
|
| restrictionNotes | string | Free-text comments clarifying or explaining the restriction (only applicable if "shippingRestriction" is not "none"). |
| isCustomsCertified | boolean | Boolean flag indicating certification status. |
| certifyingParty | string | Name of the person or entity signing the customs form. |
| nonDeliveryBehavior | string |
Specifies the action to take if the shipment cannot be delivered. Accepted values are: - `return`: The package will be returned to the sender. - `abandon`: The package will not be returned and may be discarded or handled at the carrier's discretion. Enum:
return, abandon
|
Responses
| Code | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 |
Success. The order deliveries are updated
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 422 |
Unexpected error
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| default |
Unexpected error
|
Add Deliveries to an Existing Order
Use the same POST /v2/order endpoint that created the order and its source or main delivery. Set orderAction to ADD to create one or more additional deliveries.
The request requires orderAction, orderData, and deliveries. Set orderData.orderId to the same partner-defined order ID used for the existing order. The API uses that value to associate the new deliveries with the existing order.
Each object in deliveries requires deliveryType, pickUpData, and dropOffData. Each pickup and drop-off location requires address1, city, state, and zip.
Note: The parentId field is documented for return deliveries. Do not use it to associate an ADD request with an existing order. To add a delivery to an existing order, the request must use the same orderData.orderId as the order it is being added to. The shipment or delivery ID can be any value, but if orderData.orderId does not match the existing order, the API creates a new order for that delivery instead of adding it to the existing one.
To perform rate shopping while adding the deliveries, set shopRates to true. The field defaults to false.
For the complete request and response schemas, refer to the Delivery API Swagger reference.
POST/v2/orderCreate an order with deliveries and returns
Parameters
No parameters
Request Bodyrequiredapplication/json
Use
ADD and reference an existing partner order ID.{
"orderAction": "ADD",
"orderData": {
"orderId": "ORDER-10001"
},
"deliveries": [
{
"deliveryType": "BUSINESS",
"pickUpData": {
"address1": "123 Origin St",
"city": "Orlando",
"state": "FL",
"country": "US",
"zip": "32801"
},
"dropOffData": {
"address1": "456 Destination Ave",
"city": "Tampa",
"state": "FL",
"country": "US",
"zip": "33602"
}
}
]
}| Field | Type | Description |
|---|---|---|
| orderActionrequired | string | Set to ADD. |
| orderDatarequired | object | Include the partner orderId of the existing order. |
| deliveriesrequired | Array of objects | One or more deliveries to create and associate with the existing order. |
| shopRates | boolean | Optional. Set to true to perform rate shopping; defaults to false. |
Responses
| Code | Description |
|---|---|
| 200 |
The deliveries were created and associated with the existing order.
|
| 422 |
Unexpected error.
|
Canceling a Delivery
An individual delivery can be canceled prior to it being dispatched. This can be designated by your organization or the organization sending the order (depending on your configuration).
Note: This function is only applicable for shipper cancellations.
To cancel a delivery, a POST request can be sent to the "/delivery/{id}/cancel" endpoint. The "{id}" within the URL should be replaced with the ID of the delivery that is being canceled.
For full details on this endpoint, refer to the following Swagger reference:
POST/delivery/{id}/cancelCancel a delivery
Parameters
| Name | Type | Description |
|---|---|---|
| idrequired | string(path) | delivery id |
Request Bodyoptionalapplication/json
Reason
{
"reason": {
"title": "string"
}
}| Field | Type | Description |
|---|---|---|
| reason | object | — |
| title | string | — |
Responses
| Code | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Success. The delivery has been cancelled. |
|||||||||||||||||||||
| 404 |
Resource not found
|
|||||||||||||||||||||
| default |
Unexpected error
|
Comments
0 comments
Please sign in to leave a comment.