# Customer Refunds _(Realtime-enabled)_

`GET` `POST` `PATCH` `DELETE` _(Table: EONE Transaction)_

```
eOne/core/v1.0/customerRefunds
```

Record money **refunded to a customer**, the reverse of a [customer payment](https://eonesolutions.github.io/eone-bc-integration/core-customerPayments.md). Same document, staging table and processing model as Customer Payments (resolve the customer, set the cash side with `balancingAccountNumber`, POST the applications under `customerRefunds({id})/customerPaymentApplications`), but it posts as a **Refund** and settles the customer's **credit memos** rather than invoices. It is one of the [Journal Wrappers](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

## Bound actions

Invoke with `POST /customerRefunds(<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](https://eonesolutions.github.io/eone-bc-integration/core-processedDocuments.md) 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](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

> **Note:** Approval is not done through the API. When an endpoint has **Requires Approval** set and a Business Central approval workflow is enabled for eOne documents, a refund must be **Approved** before it processes. A licensed user sends it for approval and approves it in Business Central, on the *eOne Ledger Documents* page (**Send Approval Request**, then the standard Approve/Reject/Delegate), backed by Approval User Setup. The read-only `status` (Open → Pending Approval → Approved) and `errorMessage` fields report where the document is; a failed automatic attempt lands `status` = Error with the reason in `errorMessage`.

## 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 customer'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](https://eonesolutions.github.io/eone-bc-integration/core-expenses.md) and [Bank / G/L Entries](https://eonesolutions.github.io/eone-bc-integration/core-bankGLEntries.md). 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](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

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

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

## Customer Refunds 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)_ |
| `customerId` | customerId | GUID of the resolved customer. _(ro)_ |
| `customerNumber` | customerNumber | Resolves the customer and sets the account. _(res)_ |
| `customerIntegrationId` | customerIntegrationId | Resolves the customer by integrationId and sets the account. _(res)_ |
| `customerName` | customerName | Name of the customer the document is for. _(ro)_ |
| `documentNumber` | Document No. | Payment document number. |
| `postingDate` | Posting Date | Date the payment posts to. |
| `pricesIncludeTax` | Prices Include Tax | Whether line amounts already include tax. Off (default): a line's amount is the taxable base and its taxAmount is added on top, so the line costs the document amount + tax. On: the tax is already inside the line amount and is carved back out, so the line costs the document its amount. This says only what the numbers MEAN - the tax figure itself always comes from the line's taxAmount, never from Business Central's own rate. See Journal Wrappers. |
| `documentDate` | Document Date | The document's own date; defaults to the posting date when left blank. |
| `externalDocumentNumber` | External Document No. | Caller's reference number. |
| `yourReference` | Your Reference | The payer's own reference; flows onto the resulting journal line and posted ledger entries. |
| `currencyCode` | currencyCode | ISO code; blank is LCY. _(cur)_ |
| `balancingAccountType` | Bal. Account Type | Cash side: bank or G/L account. |
| `balancingAccountId` | balancingAccountId | GUID of the resolved bank/G/L balancing account. _(ro)_ |
| `balancingAccountNumber` | Bal. Account No. | No. of the bank or G/L account the cash hits. |
| `amount` | Amount | Header total. The applications may total less than this - the difference is left on the account, unapplied - but never more. |
| `appliedAmount` | Applied Amount | Sum of the application lines. Below amount the difference posts to the account unapplied; above amount the document is rejected. _(ro)_ |
| `numberOfApplications` | No. of Applications | How many application lines the document has. _(ro)_ |
| `applicationsResolved` | Applications Resolved | How many application lines already point at a posted document and are ready to apply. _(ro)_ |
| `applicationsAwaitingInvoice` | Applications Awaiting Invoice | How many application lines name a document by integrationId that has not posted yet. Greater than zero is what puts the document in status Awaiting Invoice. _(ro)_ |
| `description` | Description | Free-text description. |
| `expectedLineCount` | Expected Line Count | How many lines or applications this document will have when it is complete. Set it on the header and the document is not processed until that many have arrived, instead of waiting out the five-minute idle window - so a document built over several calls is never processed half-built, and a complete one goes through on the next cycle. Leave it blank (the default) to keep the idle-window behaviour. |
| `declaredTotalAmount` | Declared Total Amount | Optional second check on top of expectedLineCount: the total you believe the lines add up to. When set and the arrived lines do not match it, the document fails with the difference stated rather than posting. Leave it zero to skip the check. This does not change the header amount, which stays a ceiling. |
| `deductionAmount` | Deduction Amount | Amount a third party withheld from the money before it reached the bank - a card or PSP fee, a marketplace commission. Sent as a positive magnitude, and it must be less than the document amount. Requires deductionAccountNumber. Do NOT use it for realized FX, a payment discount or application rounding: Business Central posts all three itself, and a deduction on top double-posts. |
| `deductionAccountNumber` | Deduction Account No. | G/L account the withheld amount is booked to - typically bank charges or merchant fees. Required when deductionAmount is set, and rejected without it. |
| `integrationId` | EONE Integration Id | Your external key; carried onto the resulting journal lines. |
| `journalTemplateName` | Journal Template Name | General journal template the draft lines are written to. |
| `journalBatchName` | Journal Batch Name | General journal batch the draft lines are written to; must already exist. |
| `status` | Status | Workflow state: Open, Pending Approval, Approved, Awaiting Invoice or Error. _(ro)_ |
| `errorMessage` | Error Message | Why the last automatic processing attempt failed, or which credit memo the refund is waiting for. _(ro)_ |
| `shortcutDimension1Code` | Shortcut Dimension 1 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension2Code` | Shortcut Dimension 2 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension3Code` | Shortcut Dimension 3 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension4Code` | Shortcut Dimension 4 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension5Code` | Shortcut Dimension 5 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension6Code` | Shortcut Dimension 6 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension7Code` | Shortcut Dimension 7 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension8Code` | Shortcut Dimension 8 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `createdDateTime` | SystemCreatedAt | When the integration imported this document into staging. _(ro)_ |
| `errorDateTime` | Error Date-Time | When the document last entered Error. Cleared when it is approved or reopened. _(ro)_ |
| `lastModifiedDateTime` | SystemModifiedAt | _(ro)_ |

## Related pages

Collections nested under this endpoint:

- [Customer Payment Applications](https://eonesolutions.github.io/eone-bc-integration/core-customerPaymentApplications.md)
- [Distributions](https://eonesolutions.github.io/eone-bc-integration/core-distributions.md)