Sending an advance ship notice through the API

Summary

An advance ship notice (ASN) tells the warehouse "this is coming". Through the API it is sent with POST /api/wms/asns. A single request creates the notice and its receipt, ready to be worked when the truck arrives. It is the equivalent of entering the notice by hand in Advance ship notices (ASN).

Before you start

The key and the warehouse ready: see The key, the warehouse and error responses.
Every SKU to be sent must exist in that customer's catalog, or in the warehouse's general catalog.
It helps if the customer has receiving rates, so charges are created on confirmation: see Customer rates.

The fields

Field	Required	Accepts	If left empty
`external_ref`	No	Text, up to 128 characters. The customer's purchase order or reference.	The notice has no customer reference; it is identified only by its number.
`supplier_name`	No	Text, up to 255.	No supplier.
`carrier_name`	No	Text, up to 255.	No carrier; the warehouse fills it in on arrival.
`trailer_number`	No	Text, up to 255. The trailer.	Filled in on arrival.
`expected_arrival_at`	No	A date, or date and time: `2026-10-07` or `2026-10-07 09:00`. Best in the warehouse's local time.	No expected date: it does not count in the on-time arrivals KPI.
`notes`	No	Free text.	No notes.
`lines`	Yes	A list with at least one line.	422: the notice is not created.
`lines[].sku`	Yes	Text, up to 64. Must exist.	422.
`lines[].qty`	No	A number, zero or more. Decimals allowed.	The line has an expected quantity of 0.
`lines[].uom`	No	Text, up to 16. The unit (for example `CS` or `EA`).	The product's base unit is used.

Request and response example

Northern Trading Co. announces that 120 cases of one product and 40 of another arrive on Wednesday:

POST /api/wms/asns
Authorization: Bearer 7|...
X-Warehouse-Code: DAL-01
Content-Type: application/json
Accept: application/json

{
  "external_ref": "PO-7781",
  "supplier_name": "Sample Imports",
  "carrier_name": "Southern Logistics",
  "trailer_number": "TR-4410",
  "expected_arrival_at": "2026-10-07 09:00",
  "notes": "Floor-load, do not stack",
  "lines": [
    { "sku": "NT-1001", "qty": 120, "uom": "CS" },
    { "sku": "NT-2040", "qty": 40 }
  ]
}

Response:

HTTP/1.1 201 Created
{
  "asn": {
    "id": 412,
    "asn_number": "ASN-NT-00031",
    "status": "sent",
    "external_ref": "PO-7781",
    "lines": [
      { "product_id": 3301, "expected_qty": 120, "uom_code": "CS" },
      { "product_id": 3302, "expected_qty": 40, "uom_code": "EA" }
    ]
  },
  "receipt": {
    "id": 958,
    "receipt_number": "REC-NT-00058",
    "status": "pending"
  }
}

The receipt.id (958 in the example) is what you use later to look up the receipt. Document numbers follow the customer's numbering: see Document numbering.

Tip: the response lines come in the same order they were sent and carry the internal product id, not the SKU. If the integrator needs to match them, do it by position.

What happens next

At the warehouse: the notice shows up in the ASN list as Sent ; its receipt shows up as Pending, with carrier, trailer and expected quantities already filled in. Operators get the new-receipt notification if the warehouse has it configured.
When the truck arrives: the receipt is worked as usual (Entering lines). If the warehouse has docks, the driver checks in and is linked to the job: see From notice to stock.
When the receipt is confirmed: stock goes up, the receiving charge is created, the goods received note is generated, the email goes to the customer if they have it on, and the "receipt confirmed" callback goes out if subscribed.
In the KPIs: the receipt counts toward receiving accuracy (received vs. announced) and, if it had an expected date, toward on-time arrivals.

Special cases

A SKU from the general catalog (with no customer) is also accepted.
Zero quantity: accepted, for notices where the customer does not know how much is coming. The line expects 0 and whatever is received shows as an overage.
The same SKU on two lines: two lines are created; they are not added up.
A notice that never arrives: the warehouse cancels it from the notice screen. See Cancelling or correcting a receipt.

Errors

Response	Cause	What to do
422 `unknown_sku`	A SKU does not exist. Every line is checked before writing: if one fails, nothing is created.	Add the product and resend the whole notice.
422 with `errors.lines`	No lines.	Send at least one.
422 with `errors.expected_arrival_at`	The date cannot be read.	Use `YYYY-MM-DD` or `YYYY-MM-DD HH:MM`.
422 with `errors.lines.N.qty`	A negative quantity or not a number.	Fix line N (counted from 0).

Good practices

One notice per truck, not one per day: a receipt is worked with what comes off one truck.
Send the expected date: without it the warehouse does not know when to prepare the dock and the on-time arrivals KPI does not count it.
Use the unit the warehouse will count in. If the customer announces pieces and the warehouse receives cases, the differences show up as discrepancies.

Frequently asked questions

How do we cancel a notice we sent by mistake?

Not through the API. Ask the warehouse to cancel it from the notice screen; its pending receipt is cancelled with it.

The customer reference is missing from the receipt-confirmed callback

Important: today the reference the customer sends (external_ref) is stored on the notice but is not copied to its receipt. So when you look up the receipt or get the "receipt confirmed" callback, that field comes empty. Until this is fixed, the integrator should match by the receipt's internal id (receipt.id) or its number (receipt_number), both of which come back when the notice is created.