Sales Orders Realtime-enabled

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 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.

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.
• 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.
• 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 against the posted shipment. If Business Central posts the shipment on its own schedule instead, use updateTracking on the posted salesShipment 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 (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.
• archive: snapshots the order as a new version and keeps it open; cancel archives then deletes it (soft delete). See Archiving & cancelling.

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:

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.

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 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) and the item's tariffNo / countryRegionOfOriginCode (see Items).