Advance Ship Notice API: Across Several Orders

When to use it

When one shipment (one container, one bill of lading) carries goods for several of your production orders, announce it as one advance ship notice (ASN) with POST /inbound_shipment_notices/across_orders. Every line names the production order it belongs to.

This article covers only what is different for a shipment across orders. Everything else (the notice lifecycle, announcing, accepting, cancelling, listing, receipts and error codes) works as described in Advance Ship Notice API. It is the API version of Announce across orders on the Inbound Shipments screen, and follows the same rules.

Create an advance ship notice across orders

Creates one notice covering every production order named on its lines. It is created as a draft; nothing is communicated to the brand until it is announced.

$ curl -X POST https://api.uphance.com/inbound_shipment_notices/across_orders \
    -H "Authorization: Bearer ACCESS_TOKEN"

Example Request Body:

{
  "announce": true,
  "inbound_shipment_notice": {
    "reference": "VNG000000000425",
    "warehouse_id": 12,
    "promised_in_warehouse_date": "2026-11-26",
    "carrier_name": "Maersk",
    "bill_of_lading": "SHNLLAX10260011",
    "tracking_number": "1Z999AA10123456784"
  },
  "lines": [
    { "production_order_id": 3312, 
      "sku_id": 8821, 
      "declared_quantity": 300 
    },
    {
      "production_order_id": 3313,
      "product_identifier": "SHIRT-01",
      "colour": "Navy",
      "size": "L",
      "declared_quantity": 200
    }
  ]
}

Every entry in lines must carry production_order_id, the id of the order it declares against. A line without one fails the whole request.
Each line identifies its SKU in one of two ways, as for a single order: by sku_id, or by the product_identifier, colour and size triple. The line is matched against its own order's lines only.

Use Check what may be announced once per order to get each order's SKUs and remaining quantities.

Rules every request must pass

The whole request is checked before anything is saved. If any rule fails, nothing is created and the response names what to fix.

Every order must be one you can see. An unknown order, another organisation's order, or (for a vendor login) another vendor's order returns 404 for the whole request. Uphance never creates a smaller notice from the orders that did resolve.
Every order must be confirmed and not cancelled. Otherwise 422.
All orders must belong to one vendor. Otherwise 422. Send one notice per vendor.
The orders must share a warehouse, because one shipment arrives at one site. Otherwise 422, naming the orders. Announce those orders separately.
A warehouse_id you send must be one every declared order allows, not just one of them. Otherwise 422. (A request that declares against one order only follows the single-order rule, where any of the organisation's warehouses is accepted.)
Each order and SKU may appear on one line only. Two lines for the same pair, including a sku_id line and the identifier/colour/size triple for the same SKU, return 422. They are never merged or added together.
Every declared_quantity must be a whole number of zero or more. "12units", 1.5 or -3 fail the whole request.

Warehouse and promised date when you leave them out

warehouse_id and promised_in_warehouse_date are optional, and are filled in the way the Inbound Shipments screen fills them:

warehouse_id: the first order's own warehouse when every declared order allows it, otherwise a warehouse they all allow.
promised_in_warehouse_date: the latest planned in-warehouse date among the declared orders.

When the brand accepts the notice, the promised date becomes the plan's date on every order it covers. If you leave the date out, orders planned earlier than the latest one move to that later date on acceptance. Send promised_in_warehouse_date yourself whenever you know when the shipment will arrive.

If the orders allow more than one shared warehouse, send warehouse_id so the notice goes to the site you intend.

Working with a notice that covers several orders

Once created, the notice uses the same endpoints as any other. Only the points below differ.

Update it while it is a draft

$ curl -X PATCH https://api.uphance.com/inbound_shipment_notices/NOTICE_ID \
    -H "Authorization: Bearer ACCESS_TOKEN"

Example Request Body:

{
  "inbound_shipment_notice": { "carrier_name": "MSC" },
  "lines": [
    { 
      "production_order_id": 3312, 
      "sku_id": 8821, 
      "declared_quantity": 250 
    },
    { 
      "production_order_id": 3313, 
      "sku_id": 8830, 
      "_destroy": true 
    }
  ]
}

Every line must name its production_order_id. Lines are matched by order and SKU, so the same SKU on two orders stays two lines.
"_destroy": true removes that order's line for the SKU only. Sending it again is harmless.
A line may add another order, including one whose last line you removed, if it passes the create rules: one you can see, confirmed, from the notice's vendor, and allowing the notice's warehouse.
A warehouse_id you send must be one every covered order allows. At most 200 orders, and at least one line must remain.
A refused update changes nothing, including any header fields sent with it.

Announce, accept and cancel

These work exactly as for a single-order notice. When the brand accepts, the promised date is applied to each production order the notice covers.

Receive it one order at a time

A notice covering several orders is received one order at a time. Send production_order_id with each receive request:

{
  "production_order_id": 3312,
  "quantities": { "8821": 300 },
  "external_reference": "SHNLLAX10260011-3312"
}

Without production_order_id, the request returns 422.
An order the notice does not cover returns 422.
quantities counts only what was declared against that order; anything else is ignored.
Use a different external_reference for each order, so a retried request returns the receipt it already raised.

Find it again

GET /inbound_shipment_notices?production_order_id=3313 lists every notice that declares against order 3313, including notices covering several orders.
On a notice covering several orders, production_order_id is null and production_order_number shows the first order's number only.
The lines returned by GET /inbound_shipment_notices/NOTICE_ID do not yet say which order each line belongs to. Keep your own record of the order for each line you sent.

Advance Ship Notice API: the notice lifecycle, the single-order create, and every other endpoint.
Production Orders API: the orders you may announce against.
Inventory API: Receiving Tickets: counting a receipt in.