Posted Invoice External ID (in iPaaS.com): invoice|{postedInvoiceId} — Example: invoice|7b3e4f3b-1234-4567-89ab-0c1d2e3f4a5b

Posted Invoice Line Item External ID (in iPaaS.com): {postedInvoiceLineItemId} — Example: 7b3e4f3b-1234-4567-89ab-0c1d2e3f4a5b

Customer Payment External ID (in iPaaS.com): {AppliesToInvoiceId}|{CustomerPaymentId} — Example: 7b3e4f3b-1234-4567-89ab-0c1d2e3f4a5b|9d2c1b7a-9876-4321-aaaa-bbbbccccdddd

After sync, the external ID saved in iPaaS.com follows the format invoice|{postedInvoiceId} for the parent invoice. Line items use the Business Central line item GUID directly. Customer payments use a composite format {AppliesToInvoiceId}|{CustomerPaymentId}.

Transaction created/updated in iPaaS.com where Type == “Invoice” and Status == “Complete”

Child mappings (Line, Payment, Shipping, Tax) are executed as part of the same integration when the parent Transaction meets the filter

Parent: Add/Update Dynamics Invoice FROM iPaaS.com

Child 1: Add/Update Dynamics Invoice Line FROM iPaaS.com — Maps Transaction Line items to invoice lines

Child 2: Add/Update Dynamics Invoice Customer Payment FROM iPaaS.com — Creates customer payments applied to the posted invoice

Child 3: Add/Update Dynamics Invoice Tax Line FROM iPaaS.com — Adds tax as G/L Account line items

Child 4: Add/Update Dynamics Invoice Shipping Line FROM iPaaS.com — Adds shipping as G/L Account line items

Customer/Company Requirement: The Business Central customer/company must already exist in iPaaS.com with a valid external ID. The dynamic formulas use GetExternalIdAsync to resolve the customer number.

Address Structure: Address mappings rely on an Addresses collection with IsPrimaryShipping == true and fields like Address1, City, Country, Region, PostalCode.

Payment Terms Requirement: The payment term (e.g., “COD”) must already exist in Business Central. The dynamic formula GetPaymentTermsIdByNameAsync(“COD”) will fail if the term name does not exactly match.

Customer Payment Journal Requirement: The customer payment journal (e.g., “IPAASPAY”) must already exist under Cash Management → Cash Receipt Journals.

Location and Bin Requirement: If a Location in Business Central has Bin Mandatory enabled, default bins or valid bin assignments must be configured for items, or invoice posting will fail.

Customer Location Code: If locationId is not specified in invoice line mappings, Business Central will use the customer Location Code by default.

Posted Records Mutability: Posted invoices and posted payments are restricted in Business Central; the integration is designed to create additional payments, not edit posted invoices or previously posted payments.

Payment Method Balancing Account Requirement: Do not configure a Bal. Account Type / Bal. Account No. on payment methods in Business Central (e.g., CASH) used by this integration. If a balancing account is set, Business Central automatically creates a balancing entry during posting, which leads to the payment being automatically applied and closed, preventing proper invoice linkage.

Tax Configuration Requirement: When invoice totals are mismatched due to only subtotal mapping, configure tax correctly in Business Central. Customer Setup: enable Tax Liable = TRUE and assign the correct Tax Area Code. Item Setup: assign a Tax Group Code. Shipping Setup: set Tax Group Code = NONTAXABLE on the freight G/L account. Tax Setup: define mappings between Tax Area, Tax Group, and Tax Percentage.

Duplication Handling Logic: Invoices use external IDs set to “invoice|{postedInvoiceId}”. Subsequent updates use this to determine that the invoice already exists and only payments should be added. Payments use IDs set to {AppliesToInvoiceId}|{CustomerPaymentId}, allowing the Update method to parse and PATCH the correct customerPayments({id}).

Taxes as Line Items: If taxes are available in iPaaS.com, they will be added as line items during sales invoice creation.

Mapping Collections: Enable the following:

External ID Strategy: Ensure Customer and Company records have correct Business Central external IDs. Ensure any prior order/customer sync flows populate these IDs.

Master Data: Customers and Companies present and correctly configured. Payment Terms (e.g., “Cash on delivery”) exist and are active. Customer Payment Journal “INVOICE PAYMENT” set up and ready.

Location and Bin Requirements: In Business Central, each inventory Location can be configured to require bins. When Bin Mandatory is enabled, every item transaction must have a bin defined. Users must either assign a default bin to items or use locations that do not require bins.

G/L Accounts for Shipping and Tax: Confirm that G/L account numbers such as “15930” exist and are appropriate for shipping/tax charges.

API and Permissions: API user/app with permissions to read/write salesinvoices, customerPayments, journals, and execute Microsoft.NAV.post actions.

Business Central: Uses OAuth 2.0 / application credentials configured in iPaaS.com connection. Credentials stored securely and not hard-coded.

iPaaS.com / BigCommerce (if used): Storefront and Admin API tokens stored in iPaaS.com connections and only used from server-side code.

“Invalid tax code or G/L account number is supplied” — This error occurs when Business Central rejects an invalid or non-existent tax code or G/L account number. Resolution: Align tax code and G/L account mappings between iPaaS.com and Business Central. Update static values (e.g., “15930”) to valid accounts.

“Inventory Account is missing in Inventory Posting Setup Location Code: {LocationCode}, Invt. Posting Group Code: {PostingGroup}” — Business Central cannot find an Inventory Account in Inventory Posting Setup for the specified Location Code and Posting Group. Resolution: In Business Central, open Inventory Posting Setup and configure a valid Inventory Account for the specified combination.

“Cannot convert the literal ‘MAIN’ to the expected type ‘Edm.Guid’. (locationId)” — The Business Central API expects a GUID for locationId but receives a string value. Resolution: Use a conversion formula to translate location codes to GUIDs. Update static mappings to use GUID values.

“You must specify a journal batch ID or a journal ID to get a journal line” — Business Central requires either a journalId or journalBatchId when creating journal lines. Resolution: Ensure GetCustomerPaymentJournalIdByNameAsync returns a valid journal ID. Verify the journal exists in Business Central Cash Receipt Journals.

“There is no Cust. Ledger Entry within the filter” — No Customer Ledger Entry matches the filter criteria. Resolution: Verify filter parameters match an existing open entry. Ensure the invoice is posted and still open.

“The ‘amount’ should be a negative number” — Payment amount sent as positive but Business Central expects negative. Resolution: Update payment mapping formula to convert to negative values. Verify upstream systems are not double-negating.

“The filter ‘’=‘SELLACRE24_W%2FOORINGS’’ is not valid for the No. field on the Item table” — OData filter contains invalid syntax for the field. Resolution: Fix OData filter syntax. Ensure filter values respect field length and character constraints.

“Balance must be equal to ‘0’ in G/L Account: No.={AccountNo}” — Financial transaction is not balanced. Resolution: Review the transaction to ensure debits and credits balance. Check posting setups (Customer Posting Group, General Posting Setup).

“Customer Posting Group must have a value in Customer: No.={CustomerNo}” — Customer record missing required Customer Posting Group. Resolution: In Business Central, assign a valid Customer Posting Group to the customer record.

“The field Account No. of table Gen. Journal Line contains a value ({AccountNo}) that cannot be found in the related table ({TableName})” — Journal line references a non-existent account number. Resolution: Verify the account exists in the correct table. Update mappings to use valid account numbers.

CustomerId/BillToCustomerId must resolve to a valid Business Central external ID before invoice creation.

IsInvoice must be true for the record to create a posted invoice.

Line Quantity, UnitPrice, LineType must be provided for each line.

Payment Amount must be negative and JournalId must be valid.

The static G/L account number must exist and be valid for posting.

Basic Invoice Creation: Create a Transaction in iPaaS.com with Type = “Invoice”, Status = “Complete”, valid Customer external ID, and at least one Transaction Line. Expected: Business Central shows a Posted Invoice with matching header, lines, and no payments if none provided.

Invoice with Payment: Same as above, but include a Transaction Payment record. Expected: Business Central shows the Posted Invoice plus a posted Customer Payment applied to that invoice.

Invoice Update – New Payment Only: Update the same Transaction to add another Payment. Expected: Business Central creates a new Customer Payment linked to the same posted invoice; header and lines are unchanged.

Invoice Without Shipping: Transaction with line items but ShippingAmount == null. Expected: Posted Invoice with item lines only, no shipping G/L line. Payment created normally.

Invoice with Multiple Tax Rows: Transaction with multiple tax rows in Transaction Tax. Expected: Each tax row creates a separate G/L Account line on the invoice.

Customer / Company External IDs correctly resolve to Business Central customers

Payment term name in formula matches a Business Central payment term

Location code and any required bins are configured in Business Central

Static currency, salesperson, and G/L account values are valid

Shipping and tax amounts in Business Central match source Transaction totals

Payments in Business Central reflect the correct (negative) amounts and reference the correct invoice

Static values like “USD”, “JO”, “IPAASPAY”, “EAST”, and “15930” are implementation-specific and should be reviewed and updated to match your accounting, warehouse, and reporting requirements.

If your business requires open sales orders instead of posted invoices, or different handling of adjustments/cancellations, additional collections and logic will be needed.

For any significant change to the mapping logic (e.g., new tax logic, multi-currency, dimensions), engage your MiSP or an Integrator.