Skip to main content

Receives

The Warehouse API Receives endpoint is used to instruct the warehouse of inbound shipments that will be received into inventory. This may align with upstream systems definition of Purchase Order or Advanced Shipment Notice.

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 Receive​

To create a new warehouse receive, you can make a POST request to the /warehouse/v1/receives endpoint. The JSON payload for this request should include at minimum the following fields: warehouseCode, primaryReference, and receiveLines. Here's an example of how the request should look:

POST /warehouse/v1/receives HTTP/1.1
x-api-key: your_api_key
organization-slug: your_organization_slug (if required)
Content-Type: application/json

{
  "warehouseCode": "LAW",
  "primaryReference": "12345678",
  "secondaryReference": "PO00001234",
  "eta": "2023-05-01T10:00:00+00:00",
  "transportReference": "PRO123456",
  "shipFromAddress": {
    "address": {
      "organization": "ABC Distributors",
      "addressLine1": "123 Main Street",
      "addressLine2": "",
      "country": "USA",
      "state": "CA",
      "city": "Los Angeles",
      "postalCode": "90012"
    },
    "contact": {
      "personName": "John Doe",
      "phoneNumber": "123-456-7890",
      "mobileNumber": "",
      "faxNumber": "",
      "emailAddress": "john.doe@abcdistributors.com"
    }
  },
  "receiveLines": [
    {
      "externalLineReference": "001",
      "productCode": "APL-IPH-13PRO-256-GRPH",
      "quantity": 100,
      "quantityUnit": "UNT"
    },
    {
      "externalLineReference": "002",
      "productCode": "SAM-GS22ULTRA-SILCASE-BLK",
      "quantity": 50,
      "quantityUnit": "UNT"
    },
    {
      "externalLineReference": "003",
      "productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
      "quantity": 25,
      "quantityUnit": "UNT"
    }
  ],
  "additionalReferences": [
    {
      "key": "INV",
      "value": "INV12345"
    }
  ]
}

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 receive.

{
    "data": {
        "id": "6434b6ccdd3283f909d1b990",
        "dateCreated": "2023-04-11T01:24:28+00:00",
        "dateLastUpdated": "2023-04-11T01:24:28+00:00",
        "warehouseCode": "LAW",
        "primaryReference": "12345678",
        "secondaryReference": "PO00001234",
        "status": "PRS",
        "eta": "2023-05-01T10:00:00+00:00",
        "transportReference": "PRO123456",
        "shipFromAddress": {
            "address": {
                "organization": "ABC Distributors",
                "addressLine1": "123 Main Street",
                "addressLine2": "",
                "country": "USA",
                "state": "CA",
                "city": "Los Angeles",
                "postalCode": "90012",
                "isResidential": false
            },
            "contact": {
                "personName": "John Doe",
                "phoneNumber": "123-456-7890",
                "mobileNumber": "",
                "faxNumber": "",
                "emailAddress": "john.doe@abcdistributors.com"
            }
        },
        "receiveLines": [
            {
                "lineNumber": "1",
                "externalLineReference": "001",
                "productCode": "APL-IPH-13PRO-256-GRPH",
                "quantity": 100,
                "quantityUnit": "UNT",
                "lineAttributes": [],
                "lineCustomAttributes": [],
                "partAttributes": []
            },
            {
                "lineNumber": "2",
                "externalLineReference": "002",
                "productCode": "SAM-GS22ULTRA-SILCASE-BLK",
                "quantity": 50,
                "quantityUnit": "UNT",
                "lineAttributes": [],
                "lineCustomAttributes": [],
                "partAttributes": []
            },
            {
                "lineNumber": "3",
                "externalLineReference": "003",
                "productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
                "quantity": 25,
                "quantityUnit": "UNT",
                "lineAttributes": [],
                "lineCustomAttributes": [],
                "partAttributes": []
            }
        ],
        "additionalReferences": [
            {
                "key": "INV",
                "value": "INV12345"
            }
        ],
        "shipments": [
            {
                "id": "6434b6cfdd3283f909d1b991",
                "dateCreated": "2023-04-11T01:24:31+00:00",
                "dateLastUpdated": "2023-04-11T01:24:31+00:00",
                "warehouseCode": "LAW",
                "primaryReference": "12345678",
                "secondaryReference": "PO00001234",
                "status": "PRS",
                "eta": "2023-05-01T10:00:00+00:00",
                "totalQuantity": 175,
                "shipFromAddress": {
                    "address": {
                        "organization": "ABC Distributors",
                        "addressLine1": "123 Main Street",
                        "addressLine2": "",
                        "country": "USA",
                        "state": "CA",
                        "city": "Los Angeles",
                        "postalCode": "90012",
                        "isResidential": false
                    },
                    "contact": {
                        "personName": "John Doe",
                        "phoneNumber": "123-456-7890",
                        "mobileNumber": "",
                        "faxNumber": "",
                        "emailAddress": "john.doe@abcdistributors.com"
                    }
                },
                "receiveLines": [
                    {
                        "sublines": [],
                        "lineNumber": "1",
                        "externalLineReference": "001",
                        "productCode": "APL-IPH-13PRO-256-GRPH",
                        "quantity": 100,
                        "quantityUnit": "UNT",
                        "lineAttributes": [],
                        "lineCustomAttributes": [],
                        "partAttributes": []
                    },
                    {
                        "sublines": [],
                        "lineNumber": "2",
                        "externalLineReference": "002",
                        "productCode": "SAM-GS22ULTRA-SILCASE-BLK",
                        "quantity": 50,
                        "quantityUnit": "UNT",
                        "lineAttributes": [],
                        "lineCustomAttributes": [],
                        "partAttributes": []
                    },
                    {
                        "sublines": [],
                        "lineNumber": "3",
                        "externalLineReference": "003",
                        "productCode": "HP-SPX360-14-OLED-I7-16GB-1TB-NFBLK",
                        "quantity": 25,
                        "quantityUnit": "UNT",
                        "lineAttributes": [],
                        "lineCustomAttributes": [],
                        "partAttributes": []
                    }
                ],
                "additionalReferences": [],
                "milestones": []
            }
        ]
    },
    "id": "f282ba6ca6ad435485f8cf0600ff0e61",
    "resource": [],
    "errors": []
}

The above request body includes the following:

  • warehouseCode: A string value representing the code of the warehouse where the receive will take place.
  • primaryReference: A string value representing a unique and immutable value in the upstream system.
  • secondaryReference: A string value which does not need to be unique and can be used to identify the inbound shipment.
  • transportReference: A string value which contains the PRO number, tracking number, or container number of the related shipment.
  • eta: An ISO 8601 formatted string representing the estimated time of arrival.
  • receiveLines: An array of objects representing the items being received, including the external line reference, product code, quantity, and quantity unit.

Understanding Receive Shipments​

A receive can consist of one or more shipments, which are collections of order lines associated with the receive. The receive has three primary statuses: processing (PRS), finalized (FIN), and canceled (CAN). When you submit a receive to the API and it passes validation, the receive will immediately be in the processing status. The receive will remain in the processing status until all shipments are either finalized or canceled. Once the receive is finalized, it confirms that the warehouse has physically received into inventory all of the receive lines listed under the related shipment.

The shipments list is a crucial part of each receive. It is a collection of shipments associated with a specific receive, and you can assume that one receive will have one shipment unless instructed otherwise by your Logistics Plus representative. The receive lines represent what is supposed to arrive at the warehouse, while the shipment represents what actually arrived at the warehouse. This allows you to easily determine if the receive 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 receive. 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 receive are finalized, the receive itself will also be finalized. The same can be assumed for cancellation.

Retrieving Receive Updates​

To retrieve updates for receives using the Warehouse API, you can use query parameters with the list endpoint. For instance:

GET /warehouse/v1/receives?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.

Creating a Return​

To create a return, you can simply create a receive with the added subtype set to "RET". This lets the warehouse know that this receive is a return. The return subtype can be used to differentiate the warehouse handling process for supplier inventory compared to return inventory.

The following example provides the required information for creating a warehouse receive with a subtype of return:

{
  "warehouseCode": "LAW",
  "primaryReference": "RET12345",
  "secondaryReference": "RMA98765",
  "subtype": "RET",
  "eta": "2023-05-01T10:00:00+00:00",
  "transportReference": "1Z999999999",
  "shipFromAddress": {
    "address": {
      "organization": "Customer Returns",
      "addressLine1": "789 Return Lane",
      "country": "USA",
      "state": "TX",
      "city": "Dallas",
      "postalCode": "75201"
    },
    "contact": {
      "personName": "Jane Smith",
      "phoneNumber": "214-555-0123",
      "emailAddress": "jane.smith@email.com"
    }
  },
  "receiveLines": [
    {
      "externalLineReference": "RMA-001",
      "productCode": "APL-IPH-13PRO-256-GRPH",
      "quantity": 1,
      "quantityUnit": "UNT"
    }
  ],
  "additionalReferences": [
    {
      "key": "RMA",
      "value": "RMA98765"
    }
  ]
}

The same GET methods and webhooks used for receives can also be used for returns. To retrieve updates for returns, you can follow the same approach as described in the receive.