> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/fulfillment-api/resources/tutorials/submitting-an-advanced-shipping-notice.md).

# Submitting an Advanced Shipping Notice

An Advanced Shipping Notice (ASN) is the formal notification that a physical package has been handed to a carrier and is in transit. It is submitted after the pick/pack confirmation (Tutorial 3) and marks the point at which ESW's system transitions from fulfilment-in-progress to in-transit tracking.

ESW uses the ASN to:

* Update the order status to shipped
* Trigger shopper-facing shipment notifications
* Record carrier and tracking details for customs and delivery tracking
* Reconcile ordered quantities against actually shipped quantities for partial shipments

```
POST /v1/PickPack/AdvancedShippingNotice
Authorization: Bearer <token>
Content-Type: application/json
```

***

### When to Call This Endpoint

Submit an ASN when a package has physically been handed to the carrier — not when picking or packing is complete. The sequence is:

Call the ASN endpoint:

* **At carrier collection time** — when the driver or carrier depot scan confirms the parcel has been accepted
* **At end-of-day manifest close** — when your warehouse closes the daily collection manifest
* **At label generation time** — for carriers where the label scan is the de facto handover event

***

### Request Structure

`AdvancedShippingNoticeRequest` has no hard-required fields in the schema definition, but `eswOrderReference` is functionally required for ESW to link the ASN to an order. All other fields are optional but should be provided as completely as possible.

{% code expandable="true" %}

```json
POST /v1/PickPack/AdvancedShippingNotice

{
  "shipmentId": "ASN-2024-78542-001",
  "eswOrderReference": "ESW-20241101-00012345",
  "shipmentDateTime": "2024-11-03T14:00:00.000Z",
  "shipmentStatus": "Shipped",
  "shipFrom": {
    "name": "Milan Fulfilment Centre",
    "locationCode": "FC-MILAN-01"
  },
  "carrierId": "DHL_EXPRESS",
  "carrierSCAC": "DHLX",
  "carrierReference": "DHL1234567890",
  "packageReference": "PKG-2024-78542-001",
  "packageWeight": {
    "weight": 1.45,
    "weightUnit": "KG"
  },
  "packageDimensions": {
    "length": 35.0,
    "width": 15.0,
    "height": 10.0,
    "dimensionUnit": "CM"
  },
  "items": [ ... ]
}
```

{% endcode %}

***

### &#x20;`eswOrderReference` and `shipmentId`

#### `eswOrderReference`

The ESW order reference that links this ASN to a specific order. This must exactly match the `eswOrderReference` used in the corresponding `PickPack/Confirm` call and the order reference known to ESW's fulfilment system.

```json
"eswOrderReference": "ESW-20241101-00012345"
```

#### `shipmentId`

Your unique identifier for this shipment event. Similar to `confirmationId` in PickPack/Confirm, this serves as the idempotency key — resubmitting with the same `shipmentId` allows safe retries without creating duplicate ASN records.

```json
"shipmentId": "ASN-2024-78542-001"
```

Recommended format: encode the order reference and a sequence number so the ASN is traceable back to its source order. For orders with multiple packages, use a suffix to distinguish each:

```
ASN-{orderRef}-{packageSeq}
ASN-78542-001   ← first package
ASN-78542-002   ← second package (back-order)
```

***

### `shipmentStatus`&#x20;

`shipmentStatus` describes the completeness of the shipment relative to what was ordered.

#### `"Shipped"` — complete shipment

```json
"shipmentStatus": "Shipped"
```

All ordered items are in this shipment. The order is complete from a fulfilment perspective.

**When to use:** The package contains every item from the order at the ordered quantities. No back-orders or partial fulfilments.

**ESW action:** Marks the order as fully shipped; triggers shopper shipment notification with full item list.

***

#### `"PartiallyShipped"` — some items in this shipment

```json
"shipmentStatus": "PartiallyShipped"
```

This package contains some but not all of the ordered items. One or more items will follow in a subsequent shipment or have been cancelled.

**When to use:**

* A multi-line order being shipped in multiple packages over multiple days
* Some items were out of stock and the available items are being shipped now
* Some items were cancelled and the remaining items are being shipped

**ESW action:** Updates the order status to partially shipped; sends a partial shipment notification to the shopper; keeps the order open for further ASN submissions covering remaining items.

**Important:** For each partial shipment, submit a separate ASN with `shipmentStatus: "PartiallyShipped"`. When the final package ships, use `"Shipped"` to close the order.

***

#### `"Unshipped"`&#x20;

```json
"shipmentStatus": "Unshipped"
```

The ASN is being submitted but no goods have been shipped yet. This is used to pre-register a shipment or to correct a previous ASN.

**When to use:** Advance notification before physical handover to the carrier, or when submitting a placeholder ASN that will be updated. This is an uncommon status in typical workflows — most integrations only submit ASNs at the point of actual shipment.

***

### Carrier Identification

Three fields identify the carrier handling the shipment. They are complementary and serve different purposes.

```json
"carrierId": "DHL_EXPRESS",
"carrierSCAC": "DHLX",
"carrierReference": "DHL1234567890"
```

| Field              | Description                                                                                               | Example                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `carrierId`        | ESW's internal carrier identifier — as configured in ESW's system                                         | `"DHL_EXPRESS"`, `"ROYAL_MAIL"`, `"USPS"`                       |
| `carrierSCAC`      | Standard Carrier Alpha Code — the international 2–4 letter carrier identifier used in trade and logistics | `"DHLX"` (DHL Express), `"UPSN"` (UPS), `"FDEG"` (FedEx Ground) |
| `carrierReference` | The carrier's own tracking reference for this specific package — the tracking number the shopper can use  | `"1Z999AA10123456784"` (UPS format), `"DHL1234567890"`          |

#### Which fields to provide

* Always provide `carrierReference` — this is the tracking number ESW passes to the shopper and uses for carrier tracking integration
* Provide `carrierId` if you know the ESW carrier identifier — it ensures correct carrier routing in ESW's system
* Provide `carrierSCAC` for air freight and trade documentation purposes where the standard code is required by customs systems

If only one can be provided, prioritize `carrierReference`.

***

### &#x20;`shipFrom`&#x20;

`shipFrom` identifies the warehouse or fulfilment centre from which the package was dispatched. It is used for customs documentation (origin of shipment) and for ESW's fulfilment centre reporting.

```json
"shipFrom": {
  "name": "Milan Fulfilment Centre",
  "locationCode": "FC-MILAN-01"
}
```

| Field          | Description                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| `name`         | Human-readable name of the origin location                                                             |
| `locationCode` | The fulfilment centre identifier — should match the `fulfillmentCentreId` used in inventory sync calls |

***

### `shipmentDateTime`

The timestamp of when the physical handover to the carrier occurred. Use the actual carrier collection or scan time, not the time the API call was made.

```json
"shipmentDateTime": "2024-11-03T14:00:00.000Z"
```

Always use ISO 8601 UTC format (`Z` suffix). If the carrier collected at 14:00 local time (CET = UTC+1), convert to UTC:

```
14:00 CET = 13:00 UTC → "2024-11-03T13:00:00.000Z"
```

This timestamp appears on customs documentation and in ESW's order timeline, so accuracy matters for compliance and SLA tracking.

***

### Package Weight and Dimensions

Both weight and dimensions are optional but should always be provided — they are required for customs valuation, carrier manifesting, and volumetric weight billing.

#### `packageWeight`

```json
"packageWeight": {
  "weight": 1.45,
  "weightUnit": "KG"
}
```

| Field        | Type            | Values                                         |
| ------------ | --------------- | ---------------------------------------------- |
| `weight`     | number (double) | The actual weight of the sealed, packed parcel |
| `weightUnit` | enum            | `"KG"` (kilograms) or `"LB"` (pounds)          |

#### `packageDimensions`

```json
"packageDimensions": {
  "length": 35.0,
  "width": 15.0,
  "height": 10.0,
  "dimensionUnit": "CM"
}
```

| Field           | Type            | Values                                  |
| --------------- | --------------- | --------------------------------------- |
| `length`        | number (double) | Length of the package                   |
| `width`         | number (double) | Width of the package                    |
| `height`        | number (double) | Height of the package                   |
| `dimensionUnit` | enum            | `"CM"` (centimetres) or `"IN"` (inches) |

Provide the **external** dimensions of the sealed box, not the product dimensions.

***

### &#x20;`packageReference`

```json
"packageReference": "PKG-2024-78542-001"
```

The package reference links this ASN to the corresponding package record in ESW's Package API. Use the same `packageReference` value that was used when creating the package via `POST /Package`.

This field is optional in the schema but should always be provided when using the Package API in conjunction with the Fulfilment API — it enables ESW to link the ASN, the package record, shipping labels, and customs documentation.

***

### &#x20;`items`&#x20;

`items` is an array of `ShipmentItem` objects describing what is physically in this package. It is optional for `Shipped` (all items assumed included) but required for `PartiallyShipped` to tell ESW which specific items and quantities are in this shipment.

{% code expandable="true" %}

```json
"items": [
  {
    "sku": "SKU-00123",
    "quantityOrdered": 1,
    "quantityShipped": 1,
    "unitOfMeasure": "EA",
    "itemStatus": "Shipped"
  },
  {
    "sku": "SKU-00456",
    "quantityOrdered": 2,
    "quantityShipped": 2,
    "unitOfMeasure": "EA",
    "itemStatus": "Shipped"
  }
]
```

{% endcode %}

#### `ShipmentItem` fields

| Field             | Type    | Description                                                   |
| ----------------- | ------- | ------------------------------------------------------------- |
| `sku`             | string  | The product SKU                                               |
| `quantityOrdered` | integer | Total quantity of this SKU ordered by the shopper             |
| `quantityShipped` | integer | Quantity of this SKU included in this specific shipment       |
| `unitOfMeasure`   | string  | Unit of measure — typically `"EA"` (each) for retail goods    |
| `itemStatus`      | enum    | Currently only `"Shipped"` is defined — always use this value |

#### `quantityOrdered` vs `quantityShipped`

For a complete shipment: `quantityShipped == quantityOrdered`

For a partial shipment: `quantityShipped < quantityOrdered` — the difference will ship later

```json
{
  "sku": "SKU-00456",
  "quantityOrdered": 3,
  "quantityShipped": 2,
  "unitOfMeasure": "EA",
  "itemStatus": "Shipped"
}
```

This tells ESW: 3 belts were ordered; 2 are in this package. 1 will follow.

***

### Examples

{% hint style="info" icon="arrow-progress" %}

#### Example A — Complete single-package shipment

{% endhint %}

All three items are in one package, collected by DHL Express.

{% code expandable="true" %}

```json
POST /v1/PickPack/AdvancedShippingNotice

{
  "shipmentId": "ASN-2024-78542-001",
  "eswOrderReference": "ESW-20241101-00012345",
  "shipmentDateTime": "2024-11-03T14:00:00.000Z",
  "shipmentStatus": "Shipped",
  "shipFrom": {
    "name": "Milan Fulfilment Centre",
    "locationCode": "FC-MILAN-01"
  },
  "carrierId": "DHL_EXPRESS",
  "carrierSCAC": "DHLX",
  "carrierReference": "DHL1234567890",
  "packageReference": "PKG-2024-78542-001",
  "packageWeight": {
    "weight": 1.45,
    "weightUnit": "KG"
  },
  "packageDimensions": {
    "length": 35.0,
    "width": 15.0,
    "height": 10.0,
    "dimensionUnit": "CM"
  },
  "items": [
    {
      "sku": "SKU-00123",
      "quantityOrdered": 1,
      "quantityShipped": 1,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    },
    {
      "sku": "SKU-00456",
      "quantityOrdered": 2,
      "quantityShipped": 2,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    },
    {
      "sku": "SKU-00789",
      "quantityOrdered": 1,
      "quantityShipped": 1,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    }
  ]
}
```

{% endcode %}

***

{% hint style="info" icon="arrow-progress" %}

#### Example B — Partial shipment: first package of two

{% endhint %}

The wallet and belt are ready. The scarf will ship separately once restocked.

{% code expandable="true" %}

```json
POST /v1/PickPack/AdvancedShippingNotice

{
  "shipmentId": "ASN-2024-78543-001",
  "eswOrderReference": "ESW-20241101-00012346",
  "shipmentDateTime": "2024-11-03T14:30:00.000Z",
  "shipmentStatus": "PartiallyShipped",
  "shipFrom": {
    "name": "Milan Fulfilment Centre",
    "locationCode": "FC-MILAN-01"
  },
  "carrierId": "DHL_EXPRESS",
  "carrierReference": "DHL9876543210",
  "packageReference": "PKG-2024-78543-001",
  "packageWeight": {
    "weight": 0.95,
    "weightUnit": "KG"
  },
  "packageDimensions": {
    "length": 25.0,
    "width": 15.0,
    "height": 8.0,
    "dimensionUnit": "CM"
  },
  "items": [
    {
      "sku": "SKU-00123",
      "quantityOrdered": 1,
      "quantityShipped": 1,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    },
    {
      "sku": "SKU-00456",
      "quantityOrdered": 2,
      "quantityShipped": 2,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    },
    {
      "sku": "SKU-00789",
      "quantityOrdered": 1,
      "quantityShipped": 0,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    }
  ]
}
```

{% endcode %}

Follow-up ASN when the scarf ships:

{% code expandable="true" %}

```json
{
  "shipmentId": "ASN-2024-78543-002",
  "eswOrderReference": "ESW-20241101-00012346",
  "shipmentDateTime": "2024-11-07T10:00:00.000Z",
  "shipmentStatus": "Shipped",
  "carrierId": "DHL_EXPRESS",
  "carrierReference": "DHL5678901234",
  "packageReference": "PKG-2024-78543-002",
  "packageWeight": { "weight": 0.55, "weightUnit": "KG" },
  "items": [
    {
      "sku": "SKU-00789",
      "quantityOrdered": 1,
      "quantityShipped": 1,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    }
  ]
}
```

{% endcode %}

The second ASN uses `"Shipped"` (not `"PartiallyShipped"`) because this closes out the final outstanding item.

***

{% hint style="info" icon="arrow-progress" %}

#### Example C — Single item, lightweight package, Royal Mail

{% endhint %}

{% code expandable="true" %}

```json
POST /v1/PickPack/AdvancedShippingNotice

{
  "shipmentId": "ASN-2024-78544-001",
  "eswOrderReference": "ESW-20241101-00012347",
  "shipmentDateTime": "2024-11-04T09:00:00.000Z",
  "shipmentStatus": "Shipped",
  "shipFrom": {
    "name": "Dublin Distribution Centre",
    "locationCode": "FC-DUBLIN-MAIN"
  },
  "carrierId": "ROYAL_MAIL",
  "carrierReference": "RM123456789GB",
  "packageReference": "PKG-2024-78544-001",
  "packageWeight": {
    "weight": 0.18,
    "weightUnit": "KG"
  },
  "packageDimensions": {
    "length": 22.0,
    "width": 16.0,
    "height": 4.0,
    "dimensionUnit": "CM"
  },
  "items": [
    {
      "sku": "SKU-00123",
      "quantityOrdered": 1,
      "quantityShipped": 1,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    }
  ]
}
```

{% endcode %}

***

{% hint style="info" icon="arrow-progress" %}

#### Example D — Partial quantity of same SKU shipped

{% endhint %}

3 belts ordered. 2 shipped today (in stock). 1 back-ordered.

{% code expandable="true" %}

```json
{
  "shipmentId": "ASN-2024-78545-001",
  "eswOrderReference": "ESW-20241101-00012348",
  "shipmentDateTime": "2024-11-04T11:00:00.000Z",
  "shipmentStatus": "PartiallyShipped",
  "shipFrom": {
    "name": "Milan Fulfilment Centre",
    "locationCode": "FC-MILAN-01"
  },
  "carrierId": "DHL_EXPRESS",
  "carrierReference": "DHL2345678901",
  "packageWeight": { "weight": 0.65, "weightUnit": "KG" },
  "items": [
    {
      "sku": "SKU-00456",
      "quantityOrdered": 3,
      "quantityShipped": 2,
      "unitOfMeasure": "EA",
      "itemStatus": "Shipped"
    }
  ]
}
```

{% endcode %}

***

### Common Errors

| Status                                        | Likely cause                         | Fix                                                                             |
| --------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
| `400` — `eswOrderReference` missing           | Field absent from request            | Always include `eswOrderReference`                                              |
| `400` — invalid `shipmentStatus`              | Unknown enum value                   | Use `Shipped`, `PartiallyShipped`, or `Unshipped`                               |
| `400` — invalid `weightUnit`                  | Unknown enum value                   | Use `"KG"` or `"LB"`                                                            |
| `400` — invalid `dimensionUnit`               | Unknown enum value                   | Use `"CM"` or `"IN"`                                                            |
| `400` — invalid `itemStatus`                  | Unknown enum value                   | Use `"Shipped"` — currently the only valid value                                |
| `400` — `quantityShipped` > `quantityOrdered` | Shipped more than ordered            | Verify quantities against the original order                                    |
| `202` but no order update                     | `eswOrderReference` not found in ESW | Confirm the order reference matches exactly — check for typos, case sensitivity |

***

### ASN Field Summary

```
AdvancedShippingNoticeRequest
├── shipmentId           ← your unique ASN ID — idempotency key
├── eswOrderReference    ← ESW order reference (functionally required)
├── shipmentDateTime     ← ISO 8601 UTC carrier handover time
├── shipmentStatus       ← Shipped | PartiallyShipped | Unshipped
├── shipFrom
│     ├── name           ← fulfilment centre name
│     └── locationCode   ← fulfilment centre ID (matches inventory sync)
├── carrierId            ← ESW carrier identifier
├── carrierSCAC          ← SCAC code for trade/customs
├── carrierReference     ← tracking number (provide this always)
├── packageReference     ← links to Package API record
├── packageWeight
│     ├── weight         ← sealed parcel weight
│     └── weightUnit     ← KG | LB
├── packageDimensions
│     ├── length / width / height
│     └── dimensionUnit  ← CM | IN
└── items[]
      ├── sku              ← product code
      ├── quantityOrdered  ← what was ordered
      ├── quantityShipped  ← what is in this package
      ├── unitOfMeasure    ← typically "EA"
      └── itemStatus       ← "Shipped" (only valid value)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/fulfillment-api/resources/tutorials/submitting-an-advanced-shipping-notice.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.