> 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 ## 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 | 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 | 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. *** ## Post invoice workflow **Runs when:** an invoice is posted in Younium. Sales order posting and subscription billing posting run as separate exchanges. 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/erp-and-accounting-integrations/dynamics-365-fo.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.