Orders
The warehouse order is used to instruct the warehouse to pick, pack, and ship goods to your customer. There are three primary statuses for warehouse order processing (PRS), finalized (FIN), and canceled (CAN). When the order is first sent to the API after passing validation, it will immediately be in the processing status acknowledging the order is saved and awaiting action by the warehouse. The order also contains a collection of shipments. Most orders result in one shipment. The shipment has four primary statuses entered (ENT), picking (PIC), finalized (FIN), and canceled (CAN). An order will remain in the processing status until all shipments are either finalized or canceled. When the order is finalized, it is a confirmation that all original order lines have been shipped.
Note: The full OpenAPI specification for the Logistics Plus Warehouse API is available at the following link: https://api.logisticsplus.com/warehouse/api-docs.
Create a Warehouse Order (B2C)
Below is an example of the recommended information required for a warehouse order. This example is for a customer who has ordered a single unit from an online store.
Request Data
POST /warehouse/v1/orders HTTP/1.1
x-api-key: your_api_key
organization-slug: your_organization_slug (if required)
Content-Type: application/json
{
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000012345",
"shipToAddress": {
"address": {
"organization": "John Smith",
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012"
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"orderLines": [
{
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 1,
"quantityUnit": "UNT"
}
],
"additionalReferences": [
{
"key": "ORD",
"value": "ACME1234"
}
],
"note": "BEST RATE - FEDEX OR UPS - 2DAY"
}
Replace your_api_key with your actual API key and your_organization_slug with your organization slug, if required.
If the request is successful, you will receive a 200 OK status code and a JSON response containing the newly created warehouse order.
{
"data": {
"id": "6434c71edd3283f909d1bd54",
"dateCreated": "2023-04-11T02:34:06+00:00",
"dateLastUpdated": "2023-04-11T02:34:06+00:00",
"status": "PRS",
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000012345",
"shipToAddress": {
"address": {
"organization": "John Smith",
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012",
"isResidential": false
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"orderLines": [
{
"lineNumber": "1",
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 1,
"quantityUnit": "UNT",
"lineAttributes": [],
"lineCustomAttributes": [],
"partAttributes": []
}
],
"shipments": [
{
"id": "6434c720dd3283f909d1bd55",
"status": "ENT",
"dateCreated": "2023-04-11T02:34:08+00:00",
"dateLastUpdated": "2023-04-11T02:34:08+00:00",
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000012345",
"shipToAddress": {
"address": {
"organization": "John Smith",
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012",
"isResidential": false
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"packages": [],
"shipmentLines": [
{
"sublines": [],
"lineNumber": "1",
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 1,
"quantityUnit": "UNT",
"lineAttributes": [],
"lineCustomAttributes": [],
"partAttributes": []
}
],
"milestones": [],
"additionalReferences": []
}
],
"additionalReferences": [
{
"key": "ORD",
"value": "ACME1234"
}
],
"note": "BEST RATE - FEDEX OR UPS - 2DAY"
},
"id": "e4181eed70174f29abcf2a7daeb64e66",
"resource": [],
"errors": []
}
Create a Warehouse Order (B2B)
Below is an example of the recommended information required for a warehouse order. This example is for a business customer who has ordered resupply of inventory for their retail operation.
Request Data
POST /warehouse/v1/orders HTTP/1.1
x-api-key: your_api_key
organization-slug: your_organization_slug (if required)
Content-Type: application/json
{
"warehouseCode": "LAW",
"primaryReference": "56784321",
"secondaryReference": "PO100123",
"shipToAddress": {
"address": {
"organization": "Target Store #100",
"addressLine1": "123 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012"
},
"contact": {
"personName": "Jane Doe",
"phoneNumber": "111-222-3333",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "jane.doe@target.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"orderLines": [
{
"externalLineReference": "001",
"productCode": "LGT-K380-BT-KYBD",
"quantity": 15,
"quantityUnit": "UNT"
},
{
"externalLineReference": "002",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 22,
"quantityUnit": "UNT"
},
{
"externalLineReference": "003",
"productCode": "SAM-GS22ULTRA-SILCASE-BLK",
"quantity": 20,
"quantityUnit": "UNT"
}
],
"additionalReferences": [
{
"key": "INV",
"value": "INV100123"
}
]
}
Replace your_api_key with your actual API key and your_organization_slug with your organization slug, if required.
Understanding Order Shipments
A order can consist of one or more shipments. The order has three primary statuses: processing (PRS), finalized (FIN), and canceled (CAN). When you submit an order to the API and it passes validation, the order will immediately be in the processing status. The order will remain in the processing status until all shipments are either finalized or canceled. Once the order is finalized, it confirms that the warehouse has shipped all of the order lines listed under the related shipment.
The shipments list is a crucial part of each order. It is a collection of shipments associated with a specific order, and you can assume that one order will have one shipment unless instructed otherwise by your Logistics Plus representative. The order lines represent what is supposed to ship at from warehouse, while the shipment represents what actually shipped what product attributes are on those individual lines and if applicable what packages each line is contained within. This allows you to easily determine if the order was received in full, short, or over.
Each shipment has a status (status) that can be one of the following:
PRS: Processing FIN: Finalized CAN: Canceled
Understanding the shipments list and the status of each shipment is critical to tracking the progress of your order. By checking the status of each shipment, you can see if there are any issues or delays that need to be addressed.
When all shipments related to a order are finalized, the order itself will also be finalized. The same can be assumed for cancellation.
Below is an example of a finalized warehouse order with capture release serial numbers and packing information:
{
"data": {
"id": "6434c71edd3283f909d1bd54",
"dateCreated": "2023-04-11T02:34:06+00:00",
"dateLastUpdated": "2023-04-11T02:55:29+00:00",
"status": "FIN",
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000012345",
"shipToAddress": {
"address": {
"organization": "John Smith",
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012",
"isResidential": false
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"orderLines": [
{
"lineNumber": "1",
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 1,
"quantityUnit": "UNT",
"lineAttributes": [],
"lineCustomAttributes": [],
"partAttributes": []
}
],
"shipments": [
{
"id": "6434c720dd3283f909d1bd55",
"status": "FIN",
"dateCreated": "2023-04-11T02:34:08+00:00",
"dateLastUpdated": "2023-04-11T02:55:29+00:00",
"actualShipDate": "2023-04-11T02:55:16+00:00",
"trackingDetail": {
"carrierCode": "FEDEXPELS",
"serviceLevelCode": "",
"trackingNumber": "TRACK12345678"
},
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000012345",
"shipToAddress": {
"address": {
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "US",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012",
"isResidential": false
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-14T12:00:00+00:00",
"totalCost": "0",
"totalCostUnit": "USD",
"packages": [
{
"packageReference": "123456789-001",
"weight": 7.950,
"weightUnit": "LB",
"length": 14.000,
"width": 5.000,
"height": 0.800,
"dimUnit": "M",
"packageType": "BOX",
"packedLines": [
{
"quantity": 1.000,
"orderLineReference": "1",
"orderSubLineReference": "0",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK"
}
]
}
],
"shipmentLines": [
{
"sublines": [
{
"quantity": 1.000,
"partAttributes": [
{
"key": "Serial Number",
"value": "123456789"
}
]
}
],
"lineNumber": "1",
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 1.000,
"quantityUnit": "UNT",
"lineAttributes": [],
"lineCustomAttributes": [],
"partAttributes": [
{
"key": "SERIAL NUMBER",
"value": "123456789"
}
]
}
],
"milestones": [
{
"code": "WHE",
"description": "Entered",
"sequence": "1",
"actualDate": "2023-04-11T02:34:08+00:00"
},
{
"code": "WHI",
"description": "Sent to Pick",
"sequence": "2",
"actualDate": "2023-04-11T02:47:54+00:00"
},
{
"code": "FIN",
"description": "Finalized",
"sequence": "3",
"actualDate": "2023-04-11T02:55:16+00:00"
}
],
"additionalReferences": [
{
"key": "ORD",
"value": "ACME1234"
}
]
}
],
"additionalReferences": [
{
"key": "ORD",
"value": "ACME1234"
}
],
"note": "BEST RATE - FEDEX OR UPS - 2DAY"
},
"id": "fb37dfb3ed5742e4a66053467ea2b199",
"resource": [],
"errors": []
}
Retrieving Order Updates
To retrieve updates for order using the Warehouse API, you can use query parameters with the list endpoint. For instance:
GET /warehouse/v1/orders?PrimaryReference=12345678' HTTP/1.1
x-api-key: your_api_key
organization-slug: your_organization_slug (if required)
Although our query parameters allow you to "poll" for updates within a time range, this approach is not recommended. Due to the distributed nature of our system, there's a slight chance an update might become available through the API after it is updated, which could lead to potentially lost data.
Instead, we highly recommend using the webhooks solution for real-time updates. This ensures that you receive accurate, timely information and minimizes the risk of data loss. For more information about webhooks and how to set them up, please refer to the webhook documentation.
Rate Shopping
The Warehouse Orders API allows an option for rate shopping for specific orders. Your Logistics Plus Warehouse API packet defines valid RateGroup strings. If you do not have any defined rate groups, please get in touch with your Logistics Plus representative to configure rate shopping.
The TransportDetail field MUST be null when any value is entered into the RateGroup field. Sending both will result in a 400 error.
Example Payload:
{
"WarehouseCode": "LAW",
"PrimaryReference": "1234567890",
"ShipToAddress": {
"Address": {
"AddressLine1": "123 Street",
"Country": "US"
}
},
"TransportDetail": null,
"RateGroup": "RG",
"OrderLines": [
{
"ProductCode": "MyProduct",
"Quantity": 1.0
}
]
}
The carrier selected from rate shopping will then appear under a shipment's TrackingDetail as normal.
Example:
"Shipments": [
{
"Id": "661984dd3b469b42498d5760",
"WmsId": "W01142924",
"TrackingDetail": {
"CarrierCode": "FX",
"CarrierName": "Fedex",
"ServiceLevelCode": "GND",
"TrackingNumber": "1234567890",
},
"WarehouseCode": "LAW",
"PrimaryReference": "1234567890",
"ShipToAddress": {
"Address": {
"AddressLine1": "123 Street",
"Country": "US"
}
},
"ShipmentLines": [
{
"ProductCode": "MyProduct",
"Quantity": 1.0
}
]
}
]
Incoterms
The Warehouse API currently supports all Incoterm values for Incoterm 2020, as well as six additional values. This optional field can be passed for any order as required with the below values. For additional details regarding Incoterms and their definition we recommend the free PDF provided by the International Chamber of Commerice available here.
To pass an Incoterm a forwardingData object with an incoTerm string value must be included in the Order body. Below is an example of this.
Warehouse API currently does not validate based on the warehouse country and the country that the order is being shipped to. If an invalid value is passed our warehousing teams have been taught to override this. Future versions of WAPI will throw a 400 error if an international incoterm is used for domestic orders or if a domestic incoterm is used for an international order.
{
"WarehouseCode": "LAW",
"PrimaryReference": "12345678901",
"ShipToAddress": {
"Address": {
"AddressLine1": "123 Street",
"Country": "CA"
}
},
"TransportDetail": {
"carrierCode" : "FX",
"serviceLevelCode": "GND",
},
"forwardingData": {
"incoTerm" : "DDP",
},
"OrderLines": [
{
"ProductCode": "MyProduct",
"Quantity": 1.0
}
]
}
Incoterm Accepted Values
| Value | Description | International | Domestic |
|---|---|---|---|
| PPD | Prepaid | ✔️ | |
| CLT | Collect | ✔️ | |
| C3P | Collect 3rd Party | ✔️ | |
| FCD | Collect COD | ✔️ | |
| CFR | Cost And Freight | ✔️ | |
| CIF | Cost, Insurance And Freight | ✔️ | |
| CIP | Carriage and Insurance Paid To | ✔️ | |
| CPT | Carriage Paid To | ✔️ | |
| DAP | Delivered At Place | ✔️ | |
| DAT | Delivered At Terminal | ✔️ | |
| DDP | Delivered Duty Paid | ✔️ | |
| DPU | Delivered at Place Unloaded | ✔️ | |
| EXW | Ex Works | ✔️ | |
| FAS | Free Alongside Ship | ✔️ | |
| FC1 | FCA - Free Carrier (seller is responsible for origin and loading) | ✔️ | |
| FC2 | FCA - Free Carrier (buyer is responsible for origin and loading) | ✔️ | |
| FCA | FCA - Free Carrier (seller is responsible for origin, buyer for loading) | ✔️ | |
| FOB | Free On Board | ✔️ |
Updating an Order
Orders can be updated by making a PATCH call to /warehouse/v1/order/{id}. The PATCH route contains a path parameter: id which will be the Id returned from the POST request that created the order.
The same rules must be followed as when the order was created along with a few additional rules.
- The
warehouseCodemust match thewarehouseCodein the original POST that created the order. - The
primaryReferencemust match theprimaryReferencein the original POST that created the order. - All shipments on the order must have a
statusof eitherENTorHEL.
Below is an example of the request and response when updating the order that was created previously.
Request data:
PATCH /warehouse/v1/orders/6434c71edd3283f909d1bd54 HTTP/1.1
x-api-key: your_api_key
organization-slug: your_organization_slug (if required)
Content-Type: application/json
{
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000023456",
"shipToAddress": {
"address": {
"organization": "John Smith",
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012"
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"orderLines": [
{
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 3,
"quantityUnit": "UNT"
}
],
"additionalReferences": [
{
"key": "ORD",
"value": "ACME1234"
}
],
"note": "BEST RATE - FEDEX OR UPS - 2DAY"
}
If you get a 200 response back, you’ll get the updated order details back in the same response body as creating the order.
Response data:
{
"data": {
"id": "6434c71edd3283f909d1bd54",
"dateCreated": "2023-04-11T02:34:06+00:00",
"dateLastUpdated": "2023-04-11T02:34:06+00:00",
"status": "PRS",
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000023456",
"shipToAddress": {
"address": {
"organization": "John Smith",
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012",
"isResidential": false
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"orderLines": [
{
"lineNumber": "1",
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 3,
"quantityUnit": "UNT",
"lineAttributes": [],
"lineCustomAttributes": [],
"partAttributes": []
}
],
"shipments": [
{
"id": "6434c720dd3283f909d1bd55",
"status": "ENT",
"dateCreated": "2023-04-11T02:34:08+00:00",
"dateLastUpdated": "2023-04-11T02:34:08+00:00",
"warehouseCode": "LAW",
"primaryReference": "123456789",
"secondaryReference": "SO000012345",
"shipToAddress": {
"address": {
"organization": "John Smith",
"addressLine1": "1234 Main Street",
"addressLine2": "",
"country": "USA",
"state": "CA",
"city": "Los Angeles",
"postalCode": "90012",
"isResidential": false
},
"contact": {
"personName": "John Smith",
"phoneNumber": "123-456-7890",
"mobileNumber": "",
"faxNumber": "",
"emailAddress": "john.smith@gmail.com"
}
},
"requiredShipDate": "2023-05-15T00:00:00+00:00",
"packages": [],
"shipmentLines": [
{
"sublines": [],
"lineNumber": "1",
"externalLineReference": "001",
"productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
"quantity": 1,
"quantityUnit": "UNT",
"lineAttributes": [],
"lineCustomAttributes": [],
"partAttributes": []
}
],
"milestones": [],
"additionalReferences": []
}
],
"additionalReferences": [
{
"key": "ORD",
"value": "ACME1234"
}
],
"note": "BEST RATE - FEDEX OR UPS - 2DAY"
},
"id": "f7b237aa-b866-44b1-83fd-f8f713c392a7",
"resource": [],
"errors": []
}