# Customer Invoices _(Realtime-enabled)_

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

```
eOne/core/v1.0/customerInvoices
```

Post a **direct customer invoice**, a debit to the customer entered straight through the general journal (Gen. Journal Document Type **Invoice**), for charges that do not originate from a sales document. Same document and processing model as [Customer Payments](https://eonesolutions.github.io/eone-bc-integration/core-customerPayments.md); the applications collection, `customerInvoices({id})/customerPaymentApplications`, is optional (a bare invoice need not settle anything). One of the [Journal Wrappers](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

> **Note:** This is the general-journal way to raise a receivable. For invoices that come from a sales order or need lines, taxes and printing, use [Sales Invoices](https://eonesolutions.github.io/eone-bc-integration/core-salesInvoices.md) instead.

## Settling it later

A later [customer payment](https://eonesolutions.github.io/eone-bc-integration/core-customerPayments.md) settles this invoice by either application key: `appliesToInvoiceNumber`, using the `postedDocumentNumber` from [Processed Documents](https://eonesolutions.github.io/eone-bc-integration/core-processedDocuments.md), or `appliesToInvoiceIntegrationId`, using the same `integrationId` SmartConnect posted the invoice with. The invoice never appears in the posted sales invoice tables, because it posts through the general journal, but your key resolves all the same, so there is no need to read a Business Central document number back after posting. A payment staged before the invoice posts waits as **Awaiting Invoice** and applies itself when the invoice does.

## Bound actions

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

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

`process` and `post` return no body. The staged invoice 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 invoice 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 invoice. A rejected call returns the error and leaves the invoice 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, an invoice 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 invoice 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 invoice 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 invoice 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 invoice clears its error.** Any successful write to a invoice 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 invoice 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 invoice 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 Invoices 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 document 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 | Your 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 document is waiting for. _(ro)_ |
| `shortcutDimension1Code` | Shortcut Dimension 1 Code | Dimension applied to every journal line of the document. See Dimensions. |
| `shortcutDimension2Code` | Shortcut Dimension 2 Code | Dimension applied to every journal line of the document. See Dimensions. |
| `shortcutDimension3Code` | Shortcut Dimension 3 Code | Dimension applied to every journal line of the document. See Dimensions. |
| `shortcutDimension4Code` | Shortcut Dimension 4 Code | Dimension applied to every journal line of the document. See Dimensions. |
| `shortcutDimension5Code` | Shortcut Dimension 5 Code | Dimension applied to every journal line of the document. See Dimensions. |
| `shortcutDimension6Code` | Shortcut Dimension 6 Code | Dimension applied to every journal line of the document. See Dimensions. |
| `shortcutDimension7Code` | Shortcut Dimension 7 Code | Dimension applied to every journal line of the document. See Dimensions. |
| `shortcutDimension8Code` | Shortcut Dimension 8 Code | Dimension applied to every journal line of the document. 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)