# Sales Shipments _(Realtime-enabled)_

`GET` _(Table: Sales Shipment Header)_

```
eOne/core/v1.0/salesShipments
```

Read-only posted sales shipments, and, unlike the query, a **webhook source**: subscribe to be pushed the “order shipped” event the moment a shipment posts.

## Page vs. query: when to use which

This `salesShipments` **page** is change-tracked, so it can be a webhook target and supports OData navigation (`$expand=salesShipmentLines`). The separate [`salesShipmentsQuery`](https://eonesolutions.github.io/eone-bc-integration/reports-queries.md) is a flat report with richer joins (shipping-agent name, tracking-URL template, full ship-to block) but **cannot** drive webhooks. Use the page to be notified and navigate; use the query to pull and reconcile.

## Subscribing to fulfillment

Register a subscription against the entity set; Business Central notifies your endpoint when a shipment is inserted (posted). The notification carries the record id. GET it (optionally `$expand=salesShipmentLines`) to read the detail.

```
POST /subscriptions
{
  "resource": "/salesShipments",
  "notificationUrl": "https://your-endpoint",
  "clientState": "<secret>"
}
```

> **Note:** `integrationId` is the originating order's eOne integration key (stamped at post time), and `packageTrackingNumber` is the carrier number, so the notification alone tells you which order shipped and how to track it.

## Where tracking lives

The posted sales shipment is the **convergence point** for shipping writeback in every flow. See [Shipping & dispatch](https://eonesolutions.github.io/eone-bc-integration/shipping-dispatch.md). The header's `packageTrackingNumber`, written by `updateTracking` here or by `markShipped` on the order, is the shipment's tracking number, and the label file goes on the shipment via [documentAttachments](https://eonesolutions.github.io/eone-bc-integration/core-documentAttachments.md). One tracking number per shipment: a shipment split into several individually tracked boxes is not supported in the initial release, so send the consignment-level number the carrier gives you for the shipment as a whole.

## The work description

`workDescription` returns the free-text note the document was posted with. It is read-only here: the note belongs to the open document, and posting carries it across.

## Bound actions

Invoke with `POST /salesShipments(<id>)/Microsoft.NAV.<action>`:

- `updateTracking`: writes the carrier tracking number back onto a **posted** shipment. This is the return leg of a DPD/DHL-style carrier integration: the tracking number is issued after the goods ship, so it cannot be set on the open order. Business Central permits editing these fields on a posted shipment (the "Posted Sales Shpt. - Update" feature) and this action mirrors that.

```http
POST /salesShipments(<id>)/Microsoft.NAV.updateTracking
{
  "packageTrackingNumber": "1Z999AA10123456784",
  "shippingAgentCode": "DHL",
  "shippingAgentServiceCode": "EXPRESS"
}
```

Only `packageTrackingNumber` is typically needed; `shippingAgentCode` and `shippingAgentServiceCode` are optional and only written when supplied, so a tracking-only callback does not overwrite an agent already stamped from the order. The response redirects back to the updated shipment. Supplying none of the three is an error.

## Sales Shipments fields

_API column → BC field._

**Legend**

- _(req)_ required on create
- _(res)_ resolver
- _(cur)_ currency-translated
- _(ro)_ read-only
- _(ext)_ added to this endpoint by another extension (BC field name shown; its API column name is not known here)

| API | BC field | Notes |
| --- | --- | --- |
| `id` | SystemId | BC record GUID. _(ro)_ |
| `dimensionSetId` | Dimension Set ID | The dimension set this record carries. Join it to the dimensionSetEntries endpoint to resolve the full set of dimension codes and values, including any beyond the eight shortcut dimension columns. _(ro)_ |
| `bcCompanyId` | bcCompanyId | The company this row belongs to - the same GUID that appears in the request URL. Present on every endpoint so a store pooling several companies can keep them apart without relying on which URL it called. _(ro)_ |
| `bcCompanyName` | bcCompanyName | The name of the company this row belongs to. _(ro)_ |
| `integrationId` | EONE Integration Id | Originating order's key, stamped at post time. _(ro)_ |
| `number` | No. | Posted shipment number. _(ro)_ |
| `orderNumber` | Order No. | Originating sales order number. _(ro)_ |
| `sellToCustomerNumber` | Sell-to Customer No. | _(ro)_ |
| `sellToCustomerName` | Sell-to Customer Name | _(ro)_ |
| `packageTrackingNumber` | Package Tracking No. | Carrier tracking number. _(ro)_ |
| `shippingAgentCode` | Shipping Agent Code | _(ro)_ |
| `shippingAgentServiceCode` | Shipping Agent Service Code | _(ro)_ |
| `postingDate` | Posting Date | _(ro)_ |
| `documentDate` | Document Date | _(ro)_ |
| `shipmentDate` | Shipment Date | _(ro)_ |
| `requestedDeliveryDate` | Requested Delivery Date | _(ro)_ |
| `promisedDeliveryDate` | Promised Delivery Date | _(ro)_ |
| `externalDocumentNumber` | External Document No. | _(ro)_ |
| `yourReference` | Your Reference | _(ro)_ |
| `workDescription` | workDescription | The free-text work description the document was posted with. _(ro)_ |
| `shipToName` | Ship-to Name | _(ro)_ |
| `shipToAddressLine1` | Ship-to Address | _(ro)_ |
| `shipToAddressLine2` | Ship-to Address 2 | _(ro)_ |
| `shipToCity` | Ship-to City | _(ro)_ |
| `shipToCounty` | Ship-to County | _(ro)_ |
| `shipToCountryRegionCode` | Ship-to Country/Region Code | _(ro)_ |
| `shipToPostCode` | Ship-to Post Code | _(ro)_ |
| `shipToContact` | Ship-to Contact | _(ro)_ |
| `createdDateTime` | SystemCreatedAt | _(ro)_ |
| `lastModifiedDateTime` | SystemModifiedAt | _(ro)_ |

## Related pages

Collections nested under this endpoint:

- [Sales Shipment Lines](https://eonesolutions.github.io/eone-bc-integration/core-salesShipmentLines.md)