> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/erp-and-accounting-integrations/dynamics-365-bc.md).

# Microsoft Dynamics 365 Business Central

## Synchronisation scope

| Synchronisation                              | Direction                               | When it runs                                                                                |
| -------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
| Invoices and credit notes                    | Younium → Dynamics 365 Business Central | When an invoice is posted in Younium, with invoice posting on                               |
| Journals                                     | Younium → Dynamics 365 Business Central | On demand, when a posted revenue recognition or invoice journal is sent to Business Central |
| Accounts                                     | Dynamics 365 Business Central → Younium | On demand from the integration settings, or as a scheduled job                              |
| Products                                     | Dynamics 365 Business Central → Younium | On demand from the integration settings, or as a scheduled job                              |
| Currencies, exchange rates and payment terms | Dynamics 365 Business Central → Younium | On demand from the integration settings, or as a scheduled job                              |
| Chart of accounts and dimensions             | Dynamics 365 Business Central → Younium | On demand from the integration settings, or as a scheduled job                              |

Not in scope: payments, accounts sent from Younium to Business Central.

***

## Overview

The Dynamics 365 Business Central (BC) integration uses the Business Central OData API to import master data and post sales invoices or credit memos when invoices are posted in Younium. The custom fields it creates carry the Dynamics NAV naming this integration inherited, which is why some field names read `NAV` rather than `BC`; the names must not be changed.

Younium base currency must match BC local currency (LCY) from `GeneralLedgerSetup`.

***

## Authentication

Younium connects to Business Central as a registered application rather than as a named user, so the connection does not depend on any one person's account.

You provide four things: the OData URL of your Business Central environment, the name of the company Younium should post into, and the application id and secret of an Azure AD application together with the directory it belongs to. Younium checks the connection by looking that company up in Business Central; if it finds it, the connection is valid.

The connection lasts as long as the Azure AD application secret does. If that secret is revoked or allowed to expire, posting stops until a new one is entered in the integration settings.

> **Note on the company name:** The name you enter has to match the company in Business Central exactly. A mismatch reads as a failed connection rather than a missing company, so check it first when a connection that should work does not.

***

## Activation and deactivation

Activating stores the connection details and confirms Younium can reach the company you named.

Saving the settings also prepares Younium for posting: it creates the custom fields the integration needs, the deferral and dimension lists it maps to, and turns on invoice posting when you have enabled it.

Deactivating removes the settings and stops invoice posting; documents already in Business Central are untouched.

***

## Custom fields

| Entity                              | Custom field name              | Notes                              |
| ----------------------------------- | ------------------------------ | ---------------------------------- |
| Account                             | `Dynamics NAV Customer Number` | Sell-to / bill-to customer numbers |
| Product, Charge, OrderProductCharge | `Dynamics NAV Product Number`  | Line item number                   |
| Invoice                             | `Dynamics NAV Invoice Number`  | BC document number after post      |
| Invoice / Order (when EAN enabled)  | `Dynamics NAV EAN Number`      | `OIOUBL_GLN` on BC invoice         |
| —                                   | `Dynamics NAV Deferral Code`   | List for deferral templates        |
| Invoice                             | `Synched to Dynamics365 BC`    | Posting sync flag                  |

Do not rename; integration name in code is `DynamicsNAV`.

***

## Eligibility and filtering

* LCY on BC must equal Younium base currency code.
* Multi-order invoices supported when `AllowMultipleOrders`; sell-to customer rules differ from single-order.
* Credit memos when `TotalAmount.Amount < 0`.
* Custom mappings when `EnableCustomMapping` (entity **invoice**).
* Zero-amount line filters per invoice settings.

***

## Field mapping — posted invoice (Younium → BC OData)

### Create (POST SalesInvoice / SalesCreditMemo)

| Younium field                                                    | BC field                                             |
| ---------------------------------------------------------------- | ---------------------------------------------------- |
| `Invoice.Notes`                                                  | `WorkDescription`                                    |
| Order or invoice account custom **Dynamics NAV Customer Number** | `Sell_to_Customer_No` (when default mapping enabled) |
| `Invoice.YourOrderNumber` (if `MapExternalDocumentNumber`)       | `External_Document_No`                               |
| Invoice custom EAN field (if `HasEANNumber`, max 13 chars)       | `OIOUBL_GLN`                                         |
| —                                                                | `Document_Type` = `Invoice` or `Credit Memo`         |

### Update (PATCH after create)

| Younium field                                         | BC field                                       |
| ----------------------------------------------------- | ---------------------------------------------- |
| `Invoice.InvoiceDate`                                 | `Document_Date`, `Posting_Date` (`yyyy-MM-dd`) |
| `Invoice.DueDate`                                     | `Due_Date`                                     |
| `Account.DefaultPaymentTerm.Name`                     | `Payment_Terms_Code`                           |
| Bill-to customer number                               | `Bill_to_Customer_No`                          |
| Non-base currency                                     | `Currency_Code`                                |
| `YourReference` / `OurReference`                      | `Your_Reference`, `Salesperson_Code`           |
| Address fields                                        | Ship-to / bill-to address fields per handler   |
| Line product custom field / quantity / price settings | `Sales_Invoice_Line` / credit memo lines       |

Line posting uses product number custom field, optional unit price and quantity mapping, deferral codes, dimensions from `InvoiceLineDimensionCustomField`, and comment lines when `MapProductCommentLines` is set.

The dimension mapped in the integration settings can be any of the Business Central shortcut dimensions. Younium works out which dimension slot in the General Ledger Setup the mapped dimension occupies and writes the value to the matching field on the invoice or credit memo line, for both Global Dimensions 1 and 2 and Shortcut Dimensions 3 to 8.

### Write-back (Younium)

| BC field      | Younium field                                             |
| ------------- | --------------------------------------------------------- |
| Document `No` | Custom field **Dynamics NAV Invoice Number**, sync fields |

Failed line posting triggers DELETE of created BC header.

***

## Post invoice workflow

**Runs when:** an invoice is posted in Younium.

### Concurrent posting and deadlock retries

Business Central creates a sales document one invoice line at a time. When several invoices of the same company are posted together, their lines can collide in Business Central, which then refuses a request with a "deadlocked" error (HTTP 409 Conflict, or in some versions 500).

To avoid this, Younium creates at most two Business Central documents at the same time for each tenant. Further invoices wait for a free slot for up to five minutes. If no slot becomes free in that time, Younium logs an error and creates the document anyway.

When Business Central reports a deadlock, Younium deletes the document header it has created so far and creates the document again from the start, so a retry never leaves a second document in Business Central. It retries up to three times, after about 2, 5 and 10 seconds (each with up to one second of added random delay). The wait happens outside the slot, so a waiting retry does not block other invoices. If the header cannot be deleted, or the deadlock persists after the third retry, the invoice fails as for any other error and can be posted again. Other errors are not retried.

***

## Journal export

**Runs when:** a user sends a posted Revenue Recognition or Invoice journal in Younium to Business Central. The journal must be posted in Younium first.

Each posting on the journal is checked for eligibility before the run starts: postings with a zero amount, tax postings, and postings already marked as synced to Business Central are skipped. Every other posting is exported as a general journal entry.

When the run finishes, the journal's notes and the integration log record how many of the eligible postings were exported and how many Business Central rejected, as `Exported X of Y pending journal entries to Dynamics365 BC (Z rejected by BC, see integration log)`. A posting counts as rejected, rather than stopping the export, when Business Central declines it or when Younium cannot match it to a financial account or — for a tax-inclusive posting — to its tax posting; the reason is written to the integration log, and the posting is retried on the next run.

> **Note on interrupted exports:** If a run is interrupted, for example by a timeout on a large journal, the journal note instead records `Export interrupted: X of Y journal entries exported this run, Z rejected by BC, N remaining (rejected entries are retried). Press 'Send to BC' again to resume.` Successfully exported postings are checkpointed at least every 100 entries during the run, so resuming does not re-post entries Business Central has already accepted.

***

## Import jobs

Products, payment terms, financial accounts, exchange rates, dimensions, currencies, accounts.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/erp-and-accounting-integrations/dynamics-365-bc.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
