Vendor Refunds Realtime-enabled

Record a refund received from a vendor, the AP-side reverse of a vendor payment. Same document and processing model, but it posts as a Refund and settles the vendor's credit memos. Applications go under vendorRefunds({id})/vendorPaymentApplications, the one collection the vendor ledger documents share. One of the Journal Wrappers.

Bound actions

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

• validate: runs the posting checks without processing; surfaces any problem into status / errorMessage.
• process: turns the staged refund into journal lines (unposted draft, or posted, per the Setup policy).
• post: processes the refund and posts it, whatever the Setup policy says. Use it when SmartConnect decides that this one refund goes to the ledger now, rather than an administrator putting the whole endpoint on Auto Post. Only the lines this refund just wrote are posted, so other drafts sitting in the same journal batch are left alone, and the approval gate applies exactly as it does to process.

process and post return no body. The staged refund deletes itself the moment its journal lines exist, so there is nothing to echo, and the outcome lives on the Processed Documents row the same call wrote. Fetch it by the integrationId you sent the refund with - processedDocuments?$filter=integrationId eq '<your id>' - and read postedDocumentNumber, postedPostingDate, glTransactionNumber and status; after post they are already filled in. validate writes nothing and points back at the staged refund. A rejected call returns the error and leaves the refund in staging, with errorMessage describing the problem, ready to correct and retry. See Journal Wrappers.

Reading the outcome from the payload

Four read-only roll-ups come back with every read and every write, so SmartConnect can judge the refund from the response instead of the English text in errorMessage:

• appliedAmount: the sum of the application lines. It may sit below amount, and the difference is left on the vendor's account; above amount the document is rejected. Compare the two yourself when an exact match is what your process requires.
• numberOfApplications: how many application lines the refund has.
• applicationsResolved: how many of them already point at a posted document and are ready to apply.
• applicationsAwaitingInvoice: how many still name a document that has not posted. This is the count behind status = Awaiting Invoice, and it separates "one line of four is waiting" from "all four are".
• reopen: returns a failed refund to Open and clears its error, handing it back to the background job. A refund that hits status = Error is not collected again on its own, so on an Auto endpoint - where by definition nothing calls process - this is how a corrected refund gets moving. It refuses a refund that is pending approval, exactly as the Business Central action does.

appliedAmount is this family's equivalent of the totalAmount on Expenses and Bank / G/L Entries. Both are the sum of the child lines; only a ledger document also carries a header amount to check them against, which is why the name here says what the lines did. See Journal Wrappers.

What a PATCH may do

Two rules apply to every write, on the header and on its lines and applications alike.

A refund under approval cannot be changed. Once status is Pending Approval or Approved, a PATCH, a line append or a delete is rejected. What the approver signed off on is what posts. Call reopen first if the refund genuinely has to change; that is an explicit act rather than a silent revocation, and it leaves no orphaned approval entry behind.

Deleting is also a setup choice. A DELETE of a staged refund is refused when the endpoint's Allow Manual Delete switch is off on the eOne Integration Setup page. It is on by default, so nothing changes until an administrator turns it off to mark the whole document family integration-owned. The approval rule above holds regardless of the switch.

Correcting a failed refund clears its error. Any successful write to a refund whose status is Error returns it to Open and empties errorMessage, so it becomes visible to the background job again - a line or application write counts, because the failure is usually in a line. The full text of every failed attempt is kept separately and is not lost when the live message is cleared. Awaiting Invoice is left alone: that one heals itself when the invoice posts.