# Receiving and ASNs

An **ASN** (advance shipping notice) tells your dock what is arriving for a client: which SKUs, how many, and, for lot-controlled products, which lots and expiry dates. Lift sends each submitted ASN to OpenBoxes as an inbound movement into the client's depot, your team receives it there, and Lift follows the receipt and records any difference from what was expected.

ASNs live under **Inbound** in the portal sidebar.

> **Watch the video:** [Receive an ASN](/docs/videos/3pl-receive-asn) (1 min) opens an ASN, prints the receiving sheet, receives it on the handheld or the desktop, and shows what arrived and any differences.

## Creating an ASN

There are four ways:

- **The form.** Choose **New ASN**. Fill in the **Client** and an **ASN reference** (both required), and optionally **Expected arrival**, **Supplier**, **Carrier**, **Freight reference** and **Notes**. Add a line for each SKU with its **Quantity**, and its **Lot** and **Expiry** where they are known. Then choose **Save as draft** or **Save and submit**.
- **A CSV upload.** Choose **Upload CSV**. Every ASN created from a file starts as a draft, so you can check it before submitting.
- **The API**, for your own systems (below).
- **Your client, in their client portal.** When you turn incoming stock on for a client and tick the people who may submit, they enter it under **Incoming stock** and it reaches you as an ASN. With **Hold for my approval** on, it waits in the **Awaiting approval** view of the **Inbound** page until you approve it or reject it. See [The Client Portal](/docs/3pl/client-portal#what-a-client-can-do-with-incoming-stock).

An ASN holds up to 500 lines. A lot is up to 64 characters, and an expiry date needs a lot.

### The ASN file

The file is UTF-8, up to **2 MB** and **5,000 rows**, one row per line. The columns are:

- **asn_reference**, **sku**, **quantity** (required). Rows with the same `asn_reference` are one ASN.
- **expected_arrival_date**, **supplier_name**, **inbound_carrier**, **freight_ref**, **notes**, **lot_number**, **expiry_date** (optional).
- **pallet_count**, **carton_count** (optional): the pallets and cartons the delivery is declared to arrive on, whole numbers from 0 to 100,000, one value per ASN. In the API they are `palletCount` and `cartonCount`. Your team confirms the real counts on the receipt; see [Client Billing](/docs/3pl/client-billing#rate-cards).

## ASN statuses

- **Draft**: not sent yet. Check it, then submit it so the dock can expect it.
- **Submitted**: Lift sends it to OpenBoxes as an inbound movement into the client's depot.
- **Waiting for setup**: Lift is still setting up this client's inbound supplier in OpenBoxes, and sends the ASN as soon as that is done.
- **Sending to OpenBoxes**: Lift is creating the inbound movement.
- **In transit**: the inbound movement is in OpenBoxes and ready to receive.
- **Receiving**: receiving has started in OpenBoxes.
- **Received**: everything expected has been received.
- **Closed**: nothing about this ASN changes any more. A received ASN with nothing left open closes on its own about two hours after the receipt.
- **Cancelled**: its reference can be used again for a new ASN.
- **Needs attention**: Lift stopped following this ASN. Contact support and we will sort it out.

## Receiving

Receiving happens in OpenBoxes, on the handheld or the desktop, against the inbound movement Lift created.

**The receiving sheet.** Open the ASN and choose **Receiving sheet** for a printable sheet with each line's SKU, lot, expiry and expected quantity, a column to write the count in, and a sign-off for who received it and when. Count damaged or expired units apart and tell the office.

**On the handheld.** Open **Receive** in the handheld app and scan the shipment number, or choose the shipment from **Shipments to receive**. For each line, scan the product, scan the lot barcode or type the lot number, enter the expiry date from the label, scan the bin you are putting it in, type how many you are receiving, and tap **Save line**. When every line is in, tap **Complete**. See [Handheld Scanning](/docs/platform-guide/handheld-scanning) for devices and set-up.

**Lot numbers for every lot-tracked SKU.** Every SKU with lot tracking needs a lot number when it is received. For most of them OpenBoxes asks for the lot and the expiry date itself. For a kit, a SKU marked as not expiring (see [Products that do not expire](/docs/3pl/skus#products-that-do-not-expire)), or a lot-tracked SKU whose lot and expiry control was turned off in OpenBoxes, the handheld still asks for the lot number before the line can be saved: scan or type the lot, then tap **Save line**. It asks only for the lot on these products, not for an expiry date. This is not done when receiving a return, where a returned unit without a lot is held for your team to settle, as before. Lift keeps the list of every lot-tracked product in OpenBoxes, as a product catalog named **Lot number required at receiving (set by Lift)**; leave it as it is, because Lift puts it back if it is changed. Products that already existed are added to that list on their own shortly after Lift is updated, and again whenever the SKU is saved or imported. If the handheld cannot read the list (for example it has no connection to OpenBoxes at that moment), it does not stop the line, and Lift still flags a missing lot on the ASN as below.

## Discrepancies

Lift compares what was received in OpenBoxes with the ASN and records each difference on the ASN's page, for example:

- **Fewer units than expected** or **More units than expected**.
- **Received under another lot** or **Received with another expiry date**.
- **Received without a lot number**: a lot-tracked SKU was received with no lot. This covers every lot-tracked SKU, including kits, SKUs marked as not expiring (see [Products that do not expire](/docs/3pl/skus#products-that-do-not-expire)) and products whose lot and expiry control was turned off in OpenBoxes. The handheld asks for the lot on all of them, so this mostly comes from a receipt made at a desk in OpenBoxes.
- **Received without an expiry date**: a lot-tracked SKU that expires was received with a lot number and no expiry date. OpenBoxes asks for the date itself while the product's lot and expiry control is on, so this usually means the control was turned off for that product in OpenBoxes. Turn it back on there and add the expiry date to the lot. The discrepancy stays on the ASN until you close it, even after the date is added. Kits and SKUs marked as not expiring are never flagged this way, and it is not raised when receiving a return.
- **Expired on arrival**.
- **Product not on this ASN**.

Each discrepancy is **Open** until it is either **Confirmed** when you close the ASN, or **Cleared** because a later receipt resolved it.

**Damaged or expired units.** Choose **Record damage** on the ASN to enter, for each line, the units that arrived damaged or expired and were not received.

**Closing an ASN.** Choose **Close ASN** and pick a reason: **Discrepancies confirmed as recorded**, **Short shipped by the supplier**, **Damaged or expired units**, **Inbound can no longer be followed in OpenBoxes** or **Other reason**.

**A delivery nobody announced.** Choose **Unplanned delivery** on the ASN it arrived with to create a new ASN linked to it.

## The receiving report

**Inbound**, **Receiving report** downloads a CSV of received lines for a client and a date range, with the expected, received and damaged quantities, the lots and expiry dates, the close reason, the discrepancies, and the minutes from arrival to stock for each ASN. A report is limited to 10,000 lines; narrow the dates for a larger one.

## The API

With a key that has the `read` and `write` scopes, held by the account owner or an Admin (see [Orders](/docs/3pl/orders#the-api) for keys and the base address `https://api.openboxes.cloud/api/v1/logistics`):

- `POST /asns`: create an ASN. The body takes `clientId`, `asnReference`, `expectedArrivalDate`, `supplierName`, `inboundCarrier`, `freightRef`, `notes`, `submit` (true to submit it at once) and `lines` of `sku`, `quantity`, `lotNumber` and `expiryDate`.
- `POST /asns/lookup`: find an ASN by client and reference, with the body `{"clientId": "...", "asnReference": "..."}`.
- `GET /asns/{asnId}`: read an ASN.
- `POST /asns/{asnId}/submit`: submit a draft.
- `POST /asns/{asnId}/cancel`: cancel it.
