> 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-fo.md).

# Microsoft Dynamics 365 Finance & Operations

## Synchronisation scope

| Synchronisation                                                               | Direction                                   | When it runs                                                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Invoices and credit notes (as sales orders or subscription billing schedules) | Younium → Dynamics 365 Finance & Operations | When an invoice is posted in Younium, with invoice posting on                                                     |
| Accounts                                                                      | Dynamics 365 Finance & Operations → Younium | On demand from the integration settings, or as a scheduled job                                                    |
| Accounts                                                                      | Younium → Dynamics 365 Finance & Operations | On demand from the integration settings, or as a scheduled job, when the integration is set to export accounts    |
| Products                                                                      | Dynamics 365 Finance & Operations → Younium | On demand from the integration settings                                                                           |
| Currencies, exchange rates and payment terms                                  | Dynamics 365 Finance & Operations → Younium | On demand from the integration settings, or as a scheduled job                                                    |
| Invoice numbers                                                               | Dynamics 365 Finance & Operations → Younium | On demand from the integration settings, or as a scheduled job, where Younium has enabled it for the legal entity |

Not in scope: payments, journals.

***

## Overview

The Dynamics 365 Finance & Operations (FO) integration posts Younium invoices into D365 FO using OData data entities. Two posting methods exist: **sales order** creation with lines, or **subscription billing** (when configured on orders). The handler selects the method from order custom fields and integration settings.

Workflow actions registered in the platform: `d365fo-post-invoice` and `d365fo-post-sub-bill` (same handler type).

***

## Authentication

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

You provide the Finance & Operations URL, the data area — the company — Younium should post into, and the credentials of an Azure AD application. Younium checks it can reach that company when you activate, and posts through Finance & Operations from then on.

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.

***

## Activation and deactivation

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

Saving the settings also creates the account and order custom fields the integration maps to — phonetic name, project number, our offer number and others — and turns invoice posting on or off to match your choice.

Deactivating stops invoice posting; documents already in Finance & Operations are untouched.

***

## Custom fields (representative)

| Entity          | Custom field name (code constant) | Purpose                             |
| --------------- | --------------------------------- | ----------------------------------- |
| Order / Invoice | `D365 FO Project Number`          | `ProjectId` on sales order when set |
| Order / Invoice | `D365 FO Order Our Offer Nr`      | Document attachment on sales order  |
| Account         | Multiple `D365FOAccount*` fields  | Account sync from FO import         |

Exact display names follow `IntegrationUtils.GetIntegrationCustomFieldName` with integration name from `Dynamics365FOConfig.IntegrationName`.

***

## Eligibility and posting method

* `Account.ExternalERPId` required on invoice account.
* Posting method resolved per order(s) linked to invoice lines: `D365FOSalesOrder` vs `D365FOSubscriptionBilling`.
* All orders on a multi-order invoice must agree on project number when used.
* Lines sorted by product line number.

***

## Field mapping — sales order path (Younium → D365 FO)

### Sales order header (`SalesOrderHeaderV2`)

| Younium field                        | D365 FO field                                                               |
| ------------------------------------ | --------------------------------------------------------------------------- |
| `Dynamics365Settings.DataAreaId`     | `DataAreaId`                                                                |
| `SalesOriginOnSalesOrder` (settings) | `SalesOrderOriginCode`                                                      |
| `Invoice.Account.ExternalERPId`      | `InvoiceCustomerAccountNumber` (no project)                                 |
| `Order.Account.ExternalERPId`        | `OrderingCustomerAccountNumber`                                             |
| Invoice/order custom project number  | `ProjectId` (when project set)                                              |
| `PaymentTermReference.Name`          | `PaymentTermsName`                                                          |
| `OurReference`                       | `OrderResponsiblePersonnelNumber`                                           |
| `YourReference`                      | `CustomersOrderReference`                                                   |
| Order/your order number logic        | `CustomerRequisitionNumber`                                                 |
| Delivery address                     | `DeliveryAddressStreet`, `City`, `ZipCode`, `CountryRegionId` (ISO alpha-3) |
| `Invoice.Notes`                      | `SalesOrderHeaderDocumentAttachment.Notes` (type TEXT)                      |
| Custom our offer nr                  | Attachment with description “Our offer no”                                  |

### Lines

Sales order lines are created from the invoice lines, carrying the product's external id, quantity, price, and any mapped invoice line custom fields.

| Younium field                            | D365 FO field             |
| ---------------------------------------- | ------------------------- |
| `InvoiceLine.ServicePeriodStartDate`     | `RevRecContractStartDate` |
| `InvoiceLine.ServicePeriodEndDate`       | `RevRecContractEndDate`   |
| `InvoiceLine.Notes` (see Settings below) | `LineDescription`         |

> **Note on one-off charges:** a one-off charge has no service period. A line for a one-off charge that would otherwise reach D365 FO with neither contract date set instead takes both `RevRecContractStartDate` and `RevRecContractEndDate` from the charge's effective start date. The revenue schedule reference is left unset for that line, because a one-off charge is not recognised over a period and would otherwise generate a schedule spanning a single point in time.

By default, the invoice line's remark is sent as `LineDescription`. An empty remark is sent as an empty value, which overwrites the product description D365 FO would otherwise show for the line.

### Settings

| Setting                                            | Description                                                                                                                                                                                                                                                       | Default |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Disable line description mapping**               | Stops the invoice line remark from being sent as `LineDescription` at all, so D365 FO always keeps its own product description for the line.                                                                                                                      | Off     |
| **Disable empty line description mapping**         | Leaves `LineDescription` out of the posted line only when the invoice line has no remark, so D365 FO keeps its own product description for that line while non-blank remarks still map through. Has no effect when line description mapping is disabled entirely. | Off     |
| **Map minimum commitment quantity on sales order** | Posts the committed volume as the line `Quantity` for a usage charge that only invoiced its minimum commitment (see below). Applies to each legal entity separately.                                                                                              | Off     |

#### Minimum commitment quantity

A usage charge with a minimum commitment invoices the committed amount from its first price tier even when no usage is reported for the period. The invoice line then carries a quantity of 0. With the setting enabled, Younium posts the first price tier's upper limit — the committed volume — as `Quantity` instead of 0. `LineAmount` is unchanged, so only the quantity moves.

The substitution applies only when all of the following hold:

* The charge type is **Usage** and the price model is **Tiered** or **Volume**.
* The invoice line quantity is exactly 0. A line with no quantity is still posted as 1.
* The first price tier starts at quantity 0 and is a **flat** price with a non-zero amount. A per-unit first tier invoices nothing at quantity 0, so there is no commitment to represent and the quantity stays 0.
* The first price tier has an upper limit. Where it has none, there is no committed volume to send: the quantity stays 0 and Younium logs a warning naming the charge and invoice line.

The substitution happens before the credit sign is applied, so a credit invoice posts the negative of the committed volume and reverses the original line. Lines for other charge types, other price models and lines with real usage are posted unchanged.

Subscription billing posts into a separate Finance & Operations entity set from ordinary sales orders.

### Write-back

Integration logs success; confirm which FO identifiers are stored on `Invoice.ExternalERPId` per posting method in subscription billing service.

***

## Field mapping — subscription billing path (Younium → D365 FO)

### Schedule header

`BillingStartDate` and `BillingEndDate` on the schedule are the earliest and latest billing period across the invoice's lines. For a line with a service period, that period is `InvoiceLine.ServicePeriodStartDate`/`ServicePeriodEndDate`; a one-off charge has no service period, so its period falls back to the charge's effective start date instead, used as both the start and the end for that line. This keeps the header in step with the schedule lines below it, and means an invoice made up entirely of one-off charges still carries a `BillingStartDate` — D365 FO rejects a schedule without one.

> **Note on one-off charges dated before recurring lines:** because the header takes the earliest date across all lines, a one-off charge whose effective date falls before every recurring line's service period widens the header period to start on that earlier date.

Each invoice line is posted as its own schedule line. By default, the price and quantity are resolved from the charge's price period: if the billing period differs from the price period, or the charge is tiered, the resolution falls back to a quantity of 1 with the whole line subtotal as the unit price.

| Younium field                            | D365 FO field       |
| ---------------------------------------- | ------------------- |
| Resolved unit price (see above)          | `UnitPrice`         |
| Resolved quantity (see above)            | `Quantity`          |
| `InvoiceLine.Total.Amount`               | `OriginalNetAmount` |
| `InvoiceLine.Notes` (see Settings below) | `LineText`          |

On a credit line, `UnitPrice`, `OriginalNetAmount`, and `Quantity` are all posted as their negated value.

By default, the invoice line's remark is sent as `LineText`. Unlike the sales order flow, D365 FO has no product description of its own to fall back to for a subscription billing line, so an empty remark leaves `LineText` blank rather than restoring any default text.

### Settings

| Setting                                                            | Description                                                                                                                                                                                                                                                  | Default |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| **Map NetAmount and FlatTier pricing method instead of Unitprice** | Posts each subscription billing line by quantity and net amount instead of unit price, so the quantity is no longer lost when the resolution above falls back to quantity 1, and prices with many decimal places are not rounded.                            | Off     |
| **Disable line text mapping**                                      | Stops the invoice line remark from being sent as `LineText` at all.                                                                                                                                                                                          | Off     |
| **Disable empty line text mapping**                                | Leaves `LineText` out of the posted line only when the invoice line has no remark. Has no effect when line text mapping is disabled entirely.                                                                                                                | Off     |
| **Map minimum commitment quantity on subscription billing**        | Posts the committed volume as the line `Quantity` for a usage charge that only invoiced its minimum commitment. Takes effect only together with **Map NetAmount and FlatTier pricing method instead of Unitprice**. Applies to each legal entity separately. | Off     |

When **Map NetAmount and FlatTier pricing method instead of Unitprice** is enabled, lines map as follows instead:

| Younium field                                    | D365 FO field   |
| ------------------------------------------------ | --------------- |
| `InvoiceLine.Quantity` (defaults to `1` if null) | `Quantity`      |
| Always `0`                                       | `UnitPrice`     |
| `InvoiceLine.Subtotal.Amount`                    | `NetAmount`     |
| Always `FlatTier`                                | `PricingMethod` |

`OriginalNetAmount` is not sent when this setting is enabled.

> **Note on credit lines with this setting enabled:** `Quantity` is posted as the negative of its absolute value, because a credit invoice keeps its original positive quantity while `Subtotal` is already negative. Posting the resolved quantity's negation directly, as the default mapping above does, would flip an already-negative quantity back to positive.

`PricingMethod` otherwise defaults to `Flat` only for lines with no service period; this setting overrides it to `FlatTier` for every line.

> **Minimum commitment quantity:** with **Map minimum commitment quantity on subscription billing** also enabled, a usage line that only invoiced its minimum commitment posts the first price tier's upper limit as `Quantity` instead of 0, under the same conditions as for sales orders (see *Minimum commitment quantity* above). `NetAmount`, `UnitPrice` and `PricingMethod` are unchanged, and a credit line posts the negative of the committed volume. Without **Map NetAmount and FlatTier pricing method instead of Unitprice**, the quantity is derived from the unit price and is left as it is.

***

## Post invoice workflow

**Runs when:** an invoice is posted in Younium. Each posted invoice is sent by one posting method, sales order or subscription billing, selected as described above.

Throttled (`ThrottledIntegration.Dynamics365FO`, 30s permit renewal).

***

## Import jobs

Accounts, currencies, exchange rates, payment terms, invoice numbers (when configured).


---

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