Sales Return Orders Realtime-enabled

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.

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 and validates Sell-to Customer No. for you. See resolvers. The store's RMA reference round-trips via integrationId on the header.

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

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 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, 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.
• createPickupLoad: the own-van alternative to a carrier return: assembles one warehouse receipt (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.
• archive / cancel: snapshot a version and keep the return open, or archive then delete it (soft delete). See Archiving & cancelling.

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