# Customer Credit Memos _(Realtime-enabled)_

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

```
eOne/core/v1.0/customerCreditMemos
```

Issue a **credit memo to a customer** through the general journal, same document and processing model as [Customer Payments](https://eonesolutions.github.io/eone-bc-integration/core-customerPayments.md), but it posts as a **Credit Memo** against the customer ledger. Use the applications collection, `customerCreditMemos({id})/customerPaymentApplications`, to settle the invoices it credits, or leave them open. One of the [Journal Wrappers](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

## Bound actions

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

- `validate`: runs the posting checks without processing; surfaces any problem into `status` / `errorMessage`.
- `process`: turns the staged credit memo into journal lines (unposted draft, or posted, per the Setup policy).
- `post`: processes the credit memo **and posts it**, whatever the Setup policy says. Use it when SmartConnect decides that this one credit memo goes to the ledger now, rather than an administrator putting the whole endpoint on Auto Post. Only the lines this credit memo 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`.
- `reopen`: returns a failed credit memo to Open and clears its error, handing it back to the background job. A credit memo 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 credit memo gets moving. It refuses a credit memo that is pending approval, exactly as the Business Central action does.

`process` and `post` return no body. The staged credit memo 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 credit memo 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 credit memo. A rejected call returns the error and leaves the credit memo 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 credit memo 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`.

### What a PATCH may do

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

**A credit memo 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 credit memo 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 credit memo 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 credit memo clears its error.** Any successful write to a credit memo 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.

## Reading the outcome from the payload

Four read-only roll-ups come back with every read and every write, so SmartConnect can judge the credit memo from the response instead of the English text in `errorMessage`: `appliedAmount` (the sum of the application lines), `numberOfApplications`, `applicationsResolved` (lines already pointing at a posted document) and `applicationsAwaitingInvoice` (lines still waiting for one to post).

An originating credit memo usually carries no application lines at all, so `numberOfApplications` and `appliedAmount` both come back `0` and the header `amount` posts on its own. That is the accepted state, not a shortfall. Once you do add application lines, `appliedAmount` has to stay at or below `amount`: any difference is left on the account unapplied, and only a total above `amount` is rejected.

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

## Customer Credit Memos 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. |
| `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 invoice the payment 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)