Microsoft Dynamics 365 Business Central – Gotchas

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

For reference_type values journal-entry and expense, id is a document number rather than a single Business Central record — both group every ledger line that shares that document number into one unified record. Listing attachments for one of these returns every file attached to any of its lines. If a document number is shared between an unposted/default grouping used for both expense and journal-entry, the same attachments can appear under both reference_type values for that document number.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

Setting status to authorised posts the credit memo; a draft remains editable while a posted one is immutable. tax_inclusive reflects the Vendor Card's "Prices Including VAT" setting and cannot be set directly. When tax_inclusive: true is sent for a document stored as tax-exclusive, each line's unit_price is written as its net value so the document totals match the sent tax-inclusive amounts.

Updating status from draft to authorised posts the credit memo. A posted credit memo is immutable and can no longer be updated.

Only a draft (unposted) Business Central Purchase Credit Memo can be deleted. Once a bill credit note has been posted (status authorised/posted), it can no longer be deleted.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

The balance field is not populated for bills. Business Central's API does not expose a remaining (unpaid) amount on purchase invoices — unlike sales invoices, which back the invoices resource — so the open remainder of a bill cannot be read. A fully paid bill can be detected via status: paid; partially paid amounts are not visible.

When a line omits tax_rate, the VAT group configured on the G/L Account Card applies. A foreign vendor's VAT business posting group can zero the line VAT regardless of the tax_rate sent. In U.S.-localized tenants the returned tax_inclusive reads false even when true was sent; line amounts are still computed inclusive of the sent tax rate, so totals match what was sent. A '400 Bad Request' error "Control 'fieldName' is read-only" means that field's 'editable' property is disabled in Business Central. bill_number and reference both map to the single vendorInvoiceNumber field, and bill_number wins — when both are sent, reference is silently discarded. On read both are populated from it and are always identical. Send only reference if you need it to survive a round trip. notes is not written — Business Central's purchase invoice has no field it maps to, so the value is silently discarded.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

meta.total_count requires $count=true OData parameter — not currently implemented. meta.total_count will not appear.

tax_inclusive cannot be set on sales documents — the returned value reflects the Customer Card's "Prices Including VAT" setting. When tax_inclusive: true is sent for a document stored as tax-exclusive, line unit_price is written as its net value so the document totals match the sent tax-inclusive amounts. When a line omits tax_rate, the VAT group configured on the Item or G/L Account Card applies. A foreign customer's VAT business posting group can zero the line VAT regardless of the tax_rate sent. A '400 Bad Request' error "Control 'fieldName' is read-only" means that field's 'editable' property is disabled in Business Central.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

Employee account type: set account.type to "employee" and account.id to the employee number (or GUID, which will be resolved automatically). Note: reading back the expense will NOT return the employee reference — employee payment lines are invisible in BC's API for draft entries, and resolve to a GL payable account when posted.

Bank account type: when an expense is created with account.type: "bank_account" and posted (status: "posted"), reading it back returns account.type: "ledger_account" with a different account.id. Business Central records posted transactions against the bank's associated G/L posting account, so the bank account identity is not preserved in the resulting ledger entries. Only account.type: "ledger_account" round-trips its account.id unchanged. line_items[].account is unaffected — expense lines are always G/L accounts and their account.id round-trips.

A posted expense (status: "posted") is read from Business Central's general ledger entries, which carry no bank-account discriminator. Its header account is therefore always returned as account.type: "ledger_account" — even when the expense was created with account.type: "bank_account" — and account.id is the bank's associated G/L posting account, not the bank account that was sent on create. line_items[].account.id is unaffected. See the create operation's gotcha for the full round-trip behaviour.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

tax_inclusive cannot be set on sales documents — the returned value reflects the Customer Card's "Prices Including VAT" setting. When tax_inclusive: true is sent for a document stored as tax-exclusive, line unit_price is written as its net value so the document totals match the sent tax-inclusive amounts. When a line omits tax_rate, the VAT group configured on the Item or G/L Account Card applies. A foreign customer's VAT business posting group can zero the line VAT regardless of the tax_rate sent. A '400 Bad Request' error "Control 'fieldName' is read-only" means that field's 'editable' property is disabled in Business Central.

Journal entries are read from the single general journal batch configured in the required journal_entries_journal_batch_name connection setting. An unfiltered list returns only that batch's draft (unposted) entries; posted entries are returned when filter[status] selects a posted status (they are read from Business Central's general ledger entries). Journal batches themselves cannot be listed or selected per request through the unified API.

currency and currency_rate are not returned. Business Central's API (the v2.0 journalLine entity) exposes no currency fields on journal lines, so amounts are always in the company's local currency.

Employee account type: journal entry lines can reference employees via the employee field (use display_id for the employee number, or id with a GUID which will be resolved automatically). Note: reading back the journal entry will NOT return the employee reference — employee lines are invisible in BC's API for draft entries, and resolve to a GL payable account when posted. Send ledger_account: {} alongside the employee field to satisfy schema validation.

Journal entries are created in the general journal batch configured in the required journal_entries_journal_batch_name connection setting — a different journal/batch cannot be selected per entry or per request.

currency and currency_rate are not supported: Business Central's API (the v2.0 journalLine entity) has no currency fields on journal lines and rejects unknown properties, so amounts are always posted in the company's local currency.

code is the value to use for the connection's expense/bill-payment journal batch settings (e.g. an integration configured with journal batch "DEFAULT" posts unposted expenses and bill payments into the journal listed here with that code). allow_vat and currency are not exposed and are always absent.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central.

If you encounter a '400 Bad Request' error indicating "Control 'fieldName' is read-only" it means the 'editable' property for this field in Microsoft Dynamics 365 Business Central is currently set to false. To resolve this issue and make the field writable, simply update the 'editable' property to true in Microsoft Dynamics 365 Business Central. Additionally, line item tax rates must be specified by tax rate code (e.g., "G3"), not by ID. In U.S.-regionalized Business Central tenants, the tax_inclusive field cannot be set to true. Business Central returns tax groups without rate values, so effective_tax_rate and total_tax_rate are both null on this connector. Reference the tax by code rather than by rate.

The limit parameter is ignored. All tracking categories (parent dimensions and their Standard dimension values) are always returned in a single response. Non-Standard dimension value types (Begin-Total, End-Total, Heading, Total) are excluded as they cannot be assigned to transactions.