# Sales Orders _(Realtime-enabled)_

`GET` `POST` `PATCH` `DELETE` _(Table: Sales Header)_

```
eOne/core/v1.0/salesOrders
```

Read and write sales order headers with a nested `salesOrderLines` collection, plus bound actions to release, ship and invoice.

## Resolve the customer without a lookup

Set the sell-to customer by your own key with `customerIntegrationId` instead of the Business Central number. The endpoint resolves it for you:

```
POST /salesOrders
{
  "customerIntegrationId": "CRM-5567",
  "salesOrderLines": [
    { "itemNumber": "1000", "quantity": 5 }
  ]
}
```

The nested `salesOrderLines` deep-insert the whole order in one call. See [Sales Order Lines](https://eonesolutions.github.io/eone-bc-integration/core-salesOrderLines.md) for how lines behave (item resolver, `sequence`, tracking, bins, deferral).

A retried POST cannot create a second order. An `integrationId` already on an open order, a posted shipment or a posted invoice is rejected, and the error names that document. See [The Integration Id](https://eonesolutions.github.io/eone-bc-integration/integration-id.md).

## Setting the ship-to and bill-to address

The individual `shipTo…` / `billTo…` fields are writable directly, but two write-only control fields drive Business Central's own address logic. Use them instead of writing the columns blind:

- `shipToOptions`: `Default` copies the sell-to (customer) address into ship-to; `Custom` clears `shipToCode` so you can then write the ship-to fields freely; `Alternate` leaves the current ship-to in place so you can point `shipToCode` at a saved [customer ship-to address](https://eonesolutions.github.io/eone-bc-integration/core-shipToAddresses.md).
- `billToOptions`: set to `Customer` to copy the sell-to address into the bill-to fields.

Both are write-only: they fire their copy/clear logic on write and read back blank. (These replace the retired standalone `shippingAddresses` endpoint; the same controls now live on each sales document.)

## The work description

`workDescription` is the free-text note on the document, the same text the Work Description box shows on the sales order in Business Central. Send it on create or update and SmartConnect replaces the whole note, send an empty string to clear it, and leave it out to keep what is already there. Every read returns it.

## Bound actions

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

- `release` / `reopen`: release the order for fulfilment, or reopen a released order back to Open for editing.
- `shipAndInvoice`: posts the order; the response redirects to the resulting posted document.
- `createWarehouseShipment`: creates a warehouse shipment from a released order at a require-shipment location; the response redirects to the resulting [warehouseShipment](https://eonesolutions.github.io/eone-bc-integration/core-warehouseShipments.md).
- `markShipped`: the simple (no-WMS) fulfilment writeback. When an external shipping tool (ShipStation, a 3PL, DPD/UPS/DHL) has shipped the order, call this with `packageTrackingNumber` (and optionally `shippingAgentCode` / `shippingAgentServiceCode`) to stamp the carrier tracking onto the order. Only supplied values are written, so a tracking-only call does not wipe an agent already set on the order. **What happens next is configured, not fixed**. See *Choosing what markShipped does* below. Attach the carrier label separately via [documentAttachments](https://eonesolutions.github.io/eone-bc-integration/core-documentAttachments.md) against the posted shipment. If Business Central posts the shipment on its own schedule instead, use `updateTracking` on the posted [salesShipment](https://eonesolutions.github.io/eone-bc-integration/core-salesShipments.md) rather than this action.
- `addFreightCharge`: appends one validated freight line to the order, for the carrier cost that comes back from a rating or label call. Send `lineType` (`GLAccount` or `Item`, case-insensitive), `no` (the G/L account or item number), `quantity`, `unitPrice`, and optionally `description` to override the description Business Central defaults from the account or item. The line type is yours to choose because whether freight posts to a G/L account or to a non-stock item depends on the company's posting setup. The line is appended at the next line number; the order must still be open, exactly as when you POST a line to `salesOrderLines`.
- `createDeliveryLoad`: assembles one [warehouse shipment](https://eonesolutions.github.io/eone-bc-integration/core-warehouseShipments.md) (an own-fleet van's delivery load) from this order plus every order in `additionalOrderNumbers` (comma-, semicolon-, or pipe-separated), stamping `routeId` onto the shipment's `integrationId`, the vehicle onto `shippingAgentCode` / `shippingAgentServiceCode`, and `routeDate` onto its shipment date. All orders must be released, share one require-shipment location, and not already be on a load. The response redirects to the resulting warehouse shipment; write the drop sequence against it via [routeStops](https://eonesolutions.github.io/eone-bc-integration/core-routeStops.md).
- `archive`: snapshots the order as a new version and keeps it open; `cancel` archives then deletes it (soft delete). See [Archiving & cancelling](https://eonesolutions.github.io/eone-bc-integration/archive.md).

## Choosing what `markShipped` does

Posting a shipment moves inventory and the general ledger, so whether an external system is allowed to trigger it is a decision for the company, not a hardcoded behaviour. **Fulfilment Mode** on the *eOne Integration Setup* card decides what `markShipped` does after it has stamped the carrier details:

| Fulfilment Mode | What `markShipped` does | Response |
| --- | --- | --- |
| Post Shipment *(default)* | Stamps, then posts the **ship only** (no invoice) | Redirects to the resulting [salesShipment](https://eonesolutions.github.io/eone-bc-integration/core-salesShipments.md) |
| Release Order | Stamps, then **releases** the order so a warehouse user (or a later `shipAndInvoice`) posts it | Stays on the order |
| Record Only | Stamps and stops; Business Central keeps ownership of posting | Stays on the order |

The mode is company-wide and there is no per-call override. Business Central bound actions have no optional parameters, so an override argument would have to be sent by every caller, changing the action's published signature and breaking existing integrations. If different behaviour is genuinely needed per order, use a different action: `shipAndInvoice` always posts, and `markShipped` under *Record Only* never does.

> **Note:** The response only redirects when a shipment was actually posted. Under Record Only and Release Order there is no posted document yet, so read the tracking back from the order (or subscribe to the posted-shipment feed) instead of expecting a redirect.

## Weight, volume and customs data for the carrier

In the simple flow there is no warehouse shipment, so the whole consignment has to be readable off the order:

- `totalGrossWeight`, `totalNetWeight` and `totalVolume` are calculated on read as the sum of *quantity × the line's per-unit value*, because Business Central stores gross weight, net weight and unit volume **per unit** on the line, not per line. The per-unit values are also exposed on [Sales Order Lines](https://eonesolutions.github.io/eone-bc-integration/core-salesOrderLines.md) if you would rather sum them yourself.
- `transactionType`, `transportMethod` and `vatCountryRegionCode` are the standard Intrastat and customs-declaration fields a commercial invoice is built from. Pair them with the customer's `eoriNumber` and `taxRegistrationNumber` (see [Customers](https://eonesolutions.github.io/eone-bc-integration/core-customers.md)) and the item's `tariffNo` / `countryRegionOfOriginCode` (see [Items](https://eonesolutions.github.io/eone-bc-integration/core-items.md)).

> **Caution:** Business Central carries **no unit** on a weight or volume value. The numbers are in whatever mass and volume units the company is set up in. The integration map is what decides they mean kg or lb, m³ or ft³; nothing in the API tells you.

> **Note:** Set `packageTrackingNumber` on the order and Business Central carries it onto the posted sales shipment at post time, where [fulfillment](https://eonesolutions.github.io/eone-bc-integration/core-warehouseShipments.md) reads it back via the `salesShipmentsQuery`.

> **Note:** Dimension columns `shortcutDimension1Code`–`8Code` are writable here — see [Dimensions](https://eonesolutions.github.io/eone-bc-integration/dimensions.md).

## Sales Orders 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)_ |
| `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)_ |
| `number` | No. | Document number; left blank, BC assigns it from the order no. series. |
| `integrationId` | EONE Integration Id | Your external order key. See integration-id. |
| `externalDocumentNumber` | External Document No. | The store's PO number. |
| `yourReference` | Your Reference | Free-text reference; also used for the store's PO. |
| `workDescription` | workDescription | The document's free-text work description. Sending it replaces the whole note, an empty string clears it, and omitting it leaves what is already there. |
| `customerNumber` | Sell-to Customer No. | Sell-to customer. One of three ways to resolve the customer. |
| `customerName` | Sell-to Customer Name | _(ro)_ |
| `customerIntegrationId` | customerIntegrationId | Resolves the sell-to customer by the customer's Integration Id. See resolvers. _(res)_ |
| `contactNumber` | Sell-to Contact No. | Sell-to contact. |
| `billToCustomerNumber` | Bill-to Customer No. | Bill-to customer. |
| `orderDate` | Order Date |  |
| `postingDate` | Posting Date |  |
| `documentDate` | Document Date |  |
| `dueDate` | Due Date |  |
| `requestedDeliveryDate` | Requested Delivery Date |  |
| `promisedDeliveryDate` | Promised Delivery Date |  |
| `currencyCode` | currencyCode | ISO code (e.g. "USD"); the operating currency is translated to/from BC's blank LCY automatically. _(cur)_ |
| `paymentTermsCode` | Payment Terms Code |  |
| `reasonCode` | Reason Code | Supplementary source code used to trace this document. |
| `paymentMethodCode` | Payment Method Code |  |
| `shipmentMethodCode` | Shipment Method Code |  |
| `pricesIncludeTax` | Prices Including VAT |  |
| `salespersonCode` | Salesperson Code |  |
| `locationCode` | Location Code | Default location for the order. See locations. |
| `partialShipping` | Shipping Advice |  |
| `shippingAgentCode` | Shipping Agent Code |  |
| `shippingAgentServiceCode` | Shipping Agent Service Code |  |
| `packageTrackingNumber` | Package Tracking No. | The shipping agent's package tracking number. Set it on the order and BC carries it onto the posted sales shipment at post time, where it is exposed by the salesShipmentsQuery. |
| `transactionType` | Transaction Type | Intrastat transaction type for the consignment (for example an outright sale versus a return or a replacement). One of the customs-declaration fields a carrier's commercial invoice needs on a cross-border shipment; the code must exist in the Transaction Type table. |
| `transportMethod` | Transport Method | Intrastat mode of transport for the consignment (road, air, sea, and so on). One of the customs-declaration fields a carrier's commercial invoice needs on a cross-border shipment; the code must exist in the Transport Method table. |
| `vatCountryRegionCode` | VAT Country/Region Code | Country/region whose VAT registration applies to this document, which is not always the ship-to country. Used on the customs and Intrastat declaration a carrier's commercial invoice is built from; the code must exist in the Country/Region table. |
| `sellToAddressLine1` | Sell-to Address |  |
| `sellToAddressLine2` | Sell-to Address 2 |  |
| `sellToCity` | Sell-to City |  |
| `sellToCounty` | Sell-to County |  |
| `sellToCountryRegionCode` | Sell-to Country/Region Code |  |
| `sellToPostCode` | Sell-to Post Code |  |
| `phoneNumber` | Sell-to Phone No. |  |
| `email` | Sell-to E-Mail |  |
| `billToName` | Bill-to Name |  |
| `billToAddressLine1` | Bill-to Address |  |
| `billToAddressLine2` | Bill-to Address 2 |  |
| `billToCity` | Bill-to City |  |
| `billToCounty` | Bill-to County |  |
| `billToCountryRegionCode` | Bill-to Country/Region Code |  |
| `billToPostCode` | Bill-to Post Code |  |
| `shipToName` | Ship-to Name |  |
| `shipToAddressLine1` | Ship-to Address |  |
| `shipToAddressLine2` | Ship-to Address 2 |  |
| `shipToCity` | Ship-to City |  |
| `shipToCounty` | Ship-to County |  |
| `shipToCountryRegionCode` | Ship-to Country/Region Code |  |
| `shipToPostCode` | Ship-to Post Code |  |
| `shipToContact` | Ship-to Contact |  |
| `shipToCode` | Ship-to Code | Saved ship-to address code. Setting it (the Alternate option) copies that customer ship-to address onto the document. |
| `shipToOptions` | shipToOptions | Write-only control: Default, Alternate, or Custom. Default copies the sell-to (customer) address into ship-to; Custom clears Ship-to Code so you can write ship-to fields freely; Alternate leaves the current ship-to in place so you can set a shipToCode. Reads back blank. _(res)_ |
| `billToOptions` | billToOptions | Write-only control: set to Customer to copy the sell-to (customer) address into the bill-to fields. Reads back blank. |
| `vatRegistrationNumber` | VAT Registration No. |  |
| `taxLiable` | Tax Liable |  |
| `taxAreaCode` | Tax Area Code |  |
| `genBusPostingGroup` | Gen. Bus. Posting Group | General business posting group. Defaults from the sell-to customer when the customer is resolved; set it only to override the customer's configured posting setup for this document. |
| `vatBusPostingGroup` | VAT Bus. Posting Group |  |
| `shortcutDimension1Code` | Shortcut Dimension 1 Code | See dimensions. |
| `shortcutDimension2Code` | Shortcut Dimension 2 Code | Shortcut dimension 2. See Dimensions. |
| `shortcutDimension3Code` | EONE Shortcut Dim 3 Code | Shortcut dimension 3. See Dimensions. |
| `shortcutDimension4Code` | EONE Shortcut Dim 4 Code | Shortcut dimension 4. See Dimensions. |
| `shortcutDimension5Code` | EONE Shortcut Dim 5 Code | Shortcut dimension 5. See Dimensions. |
| `shortcutDimension6Code` | EONE Shortcut Dim 6 Code | Shortcut dimension 6. See Dimensions. |
| `shortcutDimension7Code` | EONE Shortcut Dim 7 Code | Shortcut dimension 7. See Dimensions. |
| `shortcutDimension8Code` | EONE Shortcut Dim 8 Code | Shortcut dimension 8. See Dimensions. |
| `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)_ |
| `status` | Status | _(ro)_ |
| `fullyShipped` | Completely Shipped | _(ro)_ |
| `totalAmountExcludingTax` | totalAmountExcludingTax | Calculated from lines. _(ro)_ |
| `totalTaxAmount` | totalTaxAmount | Calculated from lines. _(ro)_ |
| `totalAmountIncludingTax` | totalAmountIncludingTax | Calculated from lines. _(ro)_ |
| `totalGrossWeight` | totalGrossWeight | Consignment gross weight (goods plus packaging) for the whole order, summed as quantity multiplied by each line's per-unit gross weight. Expressed in the company's mass unit. Business Central carries no unit on the value, so the integration map decides whether that is kg, lb, or something else. Use it to rate or manifest the shipment when there is no warehouse shipment. _(ro)_ |
| `totalNetWeight` | totalNetWeight | Consignment net weight (goods only) for the whole order, summed as quantity multiplied by each line's per-unit net weight. Expressed in the company's mass unit. Business Central carries no unit on the value, so the integration map decides whether that is kg, lb, or something else. Customs declarations usually ask for net rather than gross weight. _(ro)_ |
| `totalVolume` | totalVolume | Consignment volume for the whole order, summed as quantity multiplied by each line's per-unit volume. Expressed in the company's volume unit. Business Central carries no unit on the value, so the integration map decides whether that is m3, ft3, or something else. Used for volumetric (dimensional) carrier pricing. _(ro)_ |
| `lastModifiedDateTime` | SystemModifiedAt | _(ro)_ |

## Related pages

Collections nested under this endpoint:

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