# Sales Return Orders _(Realtime-enabled)_

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

```
eOne/core/v1.0/salesReturnOrders
```

Read and write Sales Return Orders (RMAs). Microsoft **excluded return orders from the standard v2 API**: the v2 sales entities are built on aggregate buffer tables that were never created for return orders. This endpoint can expose them because it binds directly to the `Sales Header` / `Sales Line` records (Document Type = Return Order), with the same eOne integration enhancements as [sales orders](https://eonesolutions.github.io/eone-bc-integration/core-salesOrders.md).

## Deep insert: header + lines in one POST

POST a complete return, header plus its `salesReturnOrderLines`, in a single call. Business Central stamps Document Type and Document No. onto each nested line automatically via the SubPageLink.

`POST` `/salesReturnOrders`

```
{
  "customerIntegrationId": "WEB-1001",
  "integrationId": "RMA-5567",
  "salesReturnOrderLines": [
    {
      "itemNumber": "1900-S",
      "quantity": 2,
      "returnQuantityToReceive": 2,
      "returnReasonCode": "DAMAGED"
    }
  ]
}
```

## Resolving the customer

The sell-to customer can be set three ways: `customerNumber` (the Business Central No.), `customerId`, or the resolver `customerIntegrationId`, which looks up the customer by its own [Integration Id](https://eonesolutions.github.io/eone-bc-integration/integration-id.md) and validates Sell-to Customer No. for you. See [resolvers](https://eonesolutions.github.io/eone-bc-integration/resolvers.md). The store's RMA reference round-trips via `integrationId` on the header.

> **Caution:** `customerIntegrationId` errors if no customer carries that Integration Id. It does not silently no-op.

## Currency code translation

Business Central stores the operating currency (LCY) as a *blank* Currency Code on documents, but API callers usually send the ISO code (e.g. `"USD"`). The endpoint translates the ISO code to blank LCY before validating, so passing your own operating currency is not rejected as a missing Currency record nor treated as a foreign currency.

## Posting: returnQuantityToReceive controls the credit

On each return line, `returnQuantityToReceive` (the returns analog of Qty. to Ship) governs how much is received and credited when the document is posted, not `quantity`, which is only the agreed return quantity.

## The carrier return leg

Business Central's native RMA flow owns the accounting. The return order becomes a return receipt and a credit memo, and nothing about that changes here. What Business Central has no concept of is the *physical* return leg: the label the customer puts on the box. That label is created outside Business Central by a shipping tool (ShipStation, a 3PL, the carrier's own portal), so the endpoint's job is the **writeback** of what that tool produced, in two parts:

- **The tracking.** `updateReturnTracking` stamps the return label's tracking number and shipping agent onto the return order itself, so the reference is on the document the goods come back against. It writes the standard `Package Tracking No.` / `Shipping Agent Code` / `Shipping Agent Service Code` fields on the Sales Header, which means the values are visible on the Sales Return Order page in the client, not parked in a shadow table. The same three values read back as `packageTrackingNumber`, `shippingAgentCode` and `shippingAgentServiceCode` on the return order, so SmartConnect can reconcile what it stamped and see whether a label was already issued before asking the shipping tool for another one. They are ordinary writable columns too: `PATCH` them directly when the carrier data arrives with the return rather than after it.
- **The label file.** `attachReturnLabel` stores the label PDF (or PNG) so it can be re-sent or re-printed. It is a convenience wrapper over [documentAttachments](https://eonesolutions.github.io/eone-bc-integration/core-documentAttachments.md), not a second attachment store: the file lands in Business Central's standard Document Attachment table and shows up in the Attachments factbox like any other attachment. Posting a `documentAttachment` with `parentType: salesReturnOrder` yourself does exactly the same thing.

> **Caution:** Carrier returns are **domestic-only**. ShipStation (and most label systems in this shape) does not generate an international return label, so a cross-border return has to be handled outside this flow. Record it as a return order without carrier data and let the customer arrange the inbound shipment.

> **Note:** **One return label per return order.** `updateReturnTracking` plus `attachReturnLabel` on the header is the whole story. Recording a return that comes back as several individually tracked boxes is not supported in the initial release: send the tracking number the label system issued for the return as a whole.

## The work description

`workDescription` is the free-text note on the document, the same text the Work Description box shows on the sales return 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 /salesReturnOrders(<id>)/Microsoft.NAV.<action>`:

- `release` / `reopen`: release the return order, or reopen a released one back to Open for editing.
- `receiveAndInvoice`: posts the return receipt and credit memo together via `Sales-Post`. Because the Sales Header is deleted on a full post, the response **redirects to the resulting [salesCreditMemo](https://eonesolutions.github.io/eone-bc-integration/posted-documents.md)** rather than back to the (now-gone) return order. The credit memo you land on is the one this call created, identified by the number Business Central stamped when it posted, so a return that was partially received and credited earlier still redirects to the new document and not to the earlier credit memo. A return order with no lines is refused before anything posts.
- `updateReturnTracking`: stamps the carrier return label's `packageTrackingNumber`, `shippingAgentCode` and `shippingAgentServiceCode` onto the return order. Only supplied values are written, so a tracking-only call does not wipe an agent already set on the return; at least one of the three is required. Unlike `markShipped` on [salesOrders](https://eonesolutions.github.io/eone-bc-integration/core-salesOrders.md), it does **not** post anything; receiving the goods stays a separate, deliberate step.
- `attachReturnLabel`: stores the carrier's return label from `fileName` + `base64Content`; the response redirects to the resulting [documentAttachment](https://eonesolutions.github.io/eone-bc-integration/core-documentAttachments.md).
- `createPickupLoad`: the own-van alternative to a carrier return: assembles one [warehouse receipt](https://eonesolutions.github.io/eone-bc-integration/core-warehouseReceipts.md) (the van's pickup load) from this return order plus every return order in `additionalOrderNumbers` (comma-, semicolon-, or pipe-separated), stamping `routeId` onto the receipt's `integrationId`, the vehicle onto its shipping-agent columns, and `routeDate` onto its receipt date. All return orders must be released, share one require-receive location, and not already be on a load. The response redirects to the resulting warehouse receipt; write the collection sequence against it via [routeStops](https://eonesolutions.github.io/eone-bc-integration/core-routeStops.md).
- `archive` / `cancel`: snapshot a version and keep the return open, or archive then delete it (soft delete). See [Archiving & cancelling](https://eonesolutions.github.io/eone-bc-integration/archive.md).

`POST` `/salesReturnOrders({id})/Microsoft.NAV.receiveAndInvoice`

> **Caution:** After a full `receiveAndInvoice` the return order record is deleted. Do not expect to GET it back; follow the redirect to the credit memo. Stamp the return tracking *before* posting, not after.

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

## Sales Return 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. |
| `integrationId` | EONE Integration Id | Your external RMA key. |
| `externalDocumentNumber` | External Document No. |  |
| `yourReference` | Your Reference |  |
| `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. | The resolver target. |
| `customerName` | Sell-to Customer Name | _(ro)_ |
| `customerIntegrationId` | customerIntegrationId | Resolves the customer by its Integration Id, then sets Sell-to Customer No. _(res)_ |
| `contactNumber` | Sell-to Contact No. |  |
| `billToCustomerNumber` | Bill-to Customer No. |  |
| `orderDate` | Order Date |  |
| `postingDate` | Posting Date |  |
| `documentDate` | Document Date |  |
| `dueDate` | Due Date |  |
| `currencyCode` | currencyCode | ISO code on the wire; blank LCY in BC. Translated on write. _(cur)_ |
| `paymentTermsCode` | Payment Terms Code |  |
| `reasonCode` | Reason Code | Supplementary source code used to trace this document. |
| `paymentMethodCode` | Payment Method Code |  |
| `shipmentMethodCode` | Shipment Method Code |  |
| `shippingAgentCode` | Shipping Agent Code | The carrier handling the return. Set it directly, or let the updateReturnTracking action stamp it when the shipping tool reports the return label back. |
| `shippingAgentServiceCode` | Shipping Agent Service Code | The carrier's service level for the return. Belongs to the shipping agent, so set the agent first. |
| `packageTrackingNumber` | Package Tracking No. | The return label's tracking number, so the goods can be traced on the way back. Usually written by the updateReturnTracking action once the carrier issues the label; readable here to confirm what was stamped. |
| `pricesIncludeTax` | Prices Including VAT |  |
| `salespersonCode` | Salesperson Code |  |
| `locationCode` | Location Code |  |
| `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 | Return-from address. |
| `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 | Shortcut dimension 1. 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)_ |
| `totalAmountExcludingTax` | totalAmountExcludingTax | Calculated from lines. _(ro)_ |
| `totalTaxAmount` | totalTaxAmount | Calculated from lines. _(ro)_ |
| `totalAmountIncludingTax` | totalAmountIncludingTax | Calculated from lines. _(ro)_ |
| `lastModifiedDateTime` | SystemModifiedAt | _(ro)_ |

## Related pages

Collections nested under this endpoint:

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