Dynamics 365 Business Central Purchase Invoice XML
The XML format documented here is used for both the import and export of purchase invoices in Dynamics 365 Business Central.
We recommend that the ExternalId field be populated with the unique ID of the purchase invoices from the external system, Zynk uses this field to track purchase invoices already imported to prevent duplicates being created in Dynamics 365 Business Central.
Tasks
- Exporting Purchase Invoices from Dynamics 365 Business Central
- Importing Purchase Invoices into Dynamics 365 Business Central
XML
Any fields not documented below are not supported with our imports / exports. Examples of where in the XML the fields should appear are shown in the samples below.
Sample Purchase Invoice File:
<?xml version="1.0" encoding="utf-8"?>
<PurchaseInvoices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PurchaseInvoice>
<Id>1acbd0e1-3965-ea11-a813-000d3a86fa27</Id>
<ExternalId>TEST-001</ExternalId>
<ODataETag>W/"JzQ0O0tTR0tUQkNUQmg3UzAxK21QbURLTTNFd3kwWjhNL05iQzBtSHpHVlp4b2c9MTswMDsn"</ODataETag>
<Number>107216</Number>
<InvoiceDate>2020-03-13T00:00:00</InvoiceDate>
<DueDate>2020-03-30T00:00:00</DueDate>
<VendorInvoiceNumber>TEST-001</VendorInvoiceNumber>
<VendorId>27db8353-0562-ea11-a812-000d3a86d6af</VendorId>
<VendorNumber>V00010</VendorNumber>
<Vendor>
<Id>27db8353-0562-ea11-a812-000d3a86d6af</Id>
<ExternalId>8888</ExternalId>
<ODataETag>W/"JzQ0O0NjdTJHN3RyM2ZWalA5cTBTRStoUlZINm94ai9GaFk4SzRsT2ZTSC9OZjQ9MTswMDsn"</ODataETag>
<Number>V00010</Number>
<DisplayName>Zynk Software</DisplayName>
<AddressLine1>6 Charlotte Square</AddressLine1>
<AddressLine2></AddressLine2>
<City>Newcastle Upon Type</City>
<State>Tyne & Wear</State>
<Country>GB</Country>
<PostCode>NE1 4XF</PostCode>
<PhoneNumber />
<Email>[email protected]</Email>
<Website>www.zynk.com</Website>
<TaxRegistrationNumber>GB123456789</TaxRegistrationNumber>
<CurrencyId>00000000-0000-0000-0000-000000000000</CurrencyId>
<CurrencyCode>GBP</CurrencyCode>
<Irs1099Code />
<PaymentTermsId>aab1e6b3-611d-ea11-bb2d-000d3a4884fc</PaymentTermsId>
<PaymentMethodId>a314deb9-611d-ea11-bb2d-000d3a4884fc</PaymentMethodId>
<TaxLiable>true</TaxLiable>
<Blocked> </Blocked>
<Balance>0</Balance>
<LastModifiedDateTime>2020-03-10T11:34:38.42Z</LastModifiedDateTime>
</Vendor>
<VendorName>Zynk Software</VendorName>
<PayToName>Zynk Software</PayToName>
<PayToContact />
<PayToVendorId>27db8353-0562-ea11-a812-000d3a86d6af</PayToVendorId>
<PayToVendor>
<Id>27db8353-0562-ea11-a812-000d3a86d6af</Id>
<ExternalId>8888</ExternalId>
<ODataETag>W/"JzQ0O0NjdTJHN3RyM2ZWalA5cTBTRStoUlZINm94ai9GaFk4SzRsT2ZTSC9OZjQ9MTswMDsn"</ODataETag>
<Number>V00010</Number>
<DisplayName>Zynk Software</DisplayName>
<AddressLine1>6 Charlotte Square</AddressLine1>
<AddressLine2></AddressLine2>
<City>Newcastle Upon Type</City>
<State>Tyne & Wear</State>
<Country>GB</Country>
<PostCode>NE1 4XF</PostCode>
<PhoneNumber />
<Email>[email protected]</Email>
<Website>www.zynk.com</Website>
<TaxRegistrationNumber>GB123456789</TaxRegistrationNumber>
<CurrencyId>00000000-0000-0000-0000-000000000000</CurrencyId>
<CurrencyCode>GBP</CurrencyCode>
<Irs1099Code />
<PaymentTermsId>aab1e6b3-611d-ea11-bb2d-000d3a4884fc</PaymentTermsId>
<PaymentMethodId>a314deb9-611d-ea11-bb2d-000d3a4884fc</PaymentMethodId>
<TaxLiable>true</TaxLiable>
<Blocked> </Blocked>
<Balance>0</Balance>
<LastModifiedDateTime>2020-03-10T11:34:38.42Z</LastModifiedDateTime>
</PayToVendor>
<PayToVendorNumber>V00010</PayToVendorNumber>
<ShipToName>John Smith</ShipToName>
<ShipToContact>John Smith</ShipToContact>
<BuyFromAddressLine1>6 Charlotte Square</BuyFromAddressLine1>
<BuyFromCity>Newcastle Upon Type</BuyFromCity>
<BuyFromState>Tyne & Wear</BuyFromState>
<BuyFromCountryLetterCode>GB</BuyFromCountryLetterCode>
<BuyFromPostCode>NE1 4XF</BuyFromPostCode>
<PayToAddressLine1>6 Charlotte Square</PayToAddressLine1>
<PayToAddressLine2 />
<PayToCity>Newcastle Upon Type</PayToCity>
<PayToCountry>GB</PayToCountry>
<PayToState>Tyne & Wear</PayToState>
<PayToPostCode>NE1 4XF</PayToPostCode>
<ShipToAddressLine1>6 Charlotte Square</ShipToAddressLine1>
<ShipToAddressLine2>Westminster</ShipToAddressLine2>
<ShipToCity>Newcastle Upon Type</ShipToCity>
<ShipToCountry>GB</ShipToCountry>
<ShipToState>Tyne & Wear</ShipToState>
<ShipToPostCode>NE1 4XF</ShipToPostCode>
<CurrencyId>00000000-0000-0000-0000-000000000000</CurrencyId>
<CurrencyCode>GBP</CurrencyCode>
<PricesIncludeTax>true</PricesIncludeTax>
<DiscountAmount>0</DiscountAmount>
<DiscountAppliedBeforeTax>false</DiscountAppliedBeforeTax>
<TotalAmountExcludingTax>1688.67</TotalAmountExcludingTax>
<TotalTaxAmount>337.73</TotalTaxAmount>
<TotalAmountIncludingTax>2026.4</TotalAmountIncludingTax>
<Status>Draft</Status>
<LastModifiedDateTime>2020-03-13T14:57:13.203Z</LastModifiedDateTime>
<PostingDate>2020-03-13T00:00:00</PostingDate>
<PurchaseInvoiceLines>
<PurchaseInvoiceLine>
<Id>1acbd0e1-3965-ea11-a813-000d3a86fa27-10000</Id>
<ExternalId>TEST-001-1</ExternalId>
<ODataETag>W/"JzQ0O1dPWkdhRFU3dEhZOEpoVHdRS3piekR5VjVDdXRTOHVvZUxqTHdSWXFIMjA9MTswMDsn"</ODataETag>
<DocumentId>1acbd0e1-3965-ea11-a813-000d3a86fa27</DocumentId>
<Sequence>10000</Sequence>
<ItemId>abb3e6b3-611d-ea11-bb2d-000d3a4884fc</ItemId>
<Item>
<Id>abb3e6b3-611d-ea11-bb2d-000d3a4884fc</Id>
<ODataETag>W/"JzQ0OzU3M1VoK1MrdElNYnp6NW13dGZHVnRIQmozQkhJOG5TOW5hZ1BWTitwWmM9MTswMDsn"</ODataETag>
<Number>1896-S</Number>
<DisplayName>ATHENS Desk</DisplayName>
<Type>Inventory</Type>
<ItemCategoryId>2f18deb9-611d-ea11-bb2d-000d3a4884fc</ItemCategoryId>
<ItemCategoryCode>TABLE</ItemCategoryCode>
<Blocked>false</Blocked>
<BaseUnitOfMeasureId>2fb4e6b3-611d-ea11-bb2d-000d3a4884fc</BaseUnitOfMeasureId>
<BaseUnitOfMeasure>
<Code>PCS</Code>
<DisplayName>Piece</DisplayName>
</BaseUnitOfMeasure>
<Gtin />
<Inventory>9</Inventory>
<UnitPrice>649.4</UnitPrice>
<PriceIncludesTax>false</PriceIncludesTax>
<UnitCost>506.6</UnitCost>
<TaxGroupId>00000000-0000-0000-0000-000000000000</TaxGroupId>
<TaxGroupCode />
</Item>
<AccountId>00000000-0000-0000-0000-000000000000</AccountId>
<Account>
<Number>10000</Number>
</Account>
<LineType>Item</LineType>
<LineObjectNumber>1896-S</LineObjectNumber>
<Description>ATHENS Desk</Description>
<UnitOfMeasureId>2d8c3bdf-549e-ed11-988a-000d3a3885d3</UnitOfMeasureId>
<UnitOfMeasureCode>PCS</UnitOfMeasureCode>
<Quantity>4</Quantity>
<DiscountAmount>0</DiscountAmount>
<DiscountPercent>0</DiscountPercent>
<DiscountAppliedBeforeTax>false</DiscountAppliedBeforeTax>
<AmountExcludingTax>0</AmountExcludingTax>
<TaxCode>STANDARD</TaxCode>
<TaxPercent>20</TaxPercent>
<TotalTaxAmount>0</TotalTaxAmount>
<AmountIncludingTax>0</AmountIncludingTax>
<NetAmount>1688.67</NetAmount>
<NetTaxAmount>337.73</NetTaxAmount>
<NetAmountIncludingTax>2026.4</NetAmountIncludingTax>
<UnitCost>506.6</UnitCost>
<InvoiceDiscountAllocation>-1688.67</InvoiceDiscountAllocation>
<ExpectedReceiptDate>2020-04-01T00:00:00</ExpectedReceiptDate>
</PurchaseInvoiceLine>
</PurchaseInvoiceLines>
</PurchaseInvoice>
</PurchaseInvoices>
In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the PurchaseInvoices schema is used below as a reference of where fields should be in the object model.
General
The following information can be found within the 'General' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| - | Id | Guid | Optional | Used for matching existing purchase invoices |
| - | ExternalId | string | Optional | Stored in Zynk's internal DB and used for matching existing purchase invoices |
| No. | Number | string | Optional | Used for matching existing purchase invoices. The next number will be used when creating a new purchase invoice if not specified |
| Vendor Invoice No. | VendorInvoiceNumber | string | Optional | |
| Vendor No. | VendorId | Guid | Optional | |
| Vendor No. | VendorNumber | string | Optional | Performs a lookup for the vendor ID based on the number |
| Vendor No. | Vendor | Vendor | Optional | Used for looking up and auto creating vendors |
| Vendor Name | VendorName | string | Read-only | |
| By-From > Address | BuyFromAddressLine1 | string | Optional | |
| By-From > Address | BuyFromAddressLine2 | string | Optional | |
| By-From > City | BuyFromCity | string | Optional | |
| By-From > County | BuyFromState | string | Optional | |
| By-From > Postcode | BuyFromPostCode | string | Optional | |
| By-From > Country/Region Code | BuyFromCountryLetterCode | string | Optional | |
| Invoice Receipt Date | InvoiceDate | DateTime | Optional | |
| Posting/Tax Point Date | PostingDate | DateTime | Optional | |
| Due Date | DueDate | DateTime | Optional | |
| Status | Status | string | Read-only | Can be: Draft, In Review, Open, Paid, Canceled, Corrective |
<?xml version="1.0" encoding="utf-8"?>
<PurchaseInvoices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PurchaseInvoice>
<Id>1acbd0e1-3965-ea11-a813-000d3a86fa27</Id>
<ExternalId>TEST-001</ExternalId>
<Number>107216</Number>
<VendorInvoiceNumber>TEST-001</VendorInvoiceNumber>
<VendorId>27db8353-0562-ea11-a812-000d3a86d6af</VendorId>
<VendorNumber>V00010</VendorNumber>
<Vendor>
<!-- See Vendor XML for more details -->
</Vendor>
<VendorName>Zynk Software</VendorName>
<BuyFromAddressLine1>6 Charlotte Square</BuyFromAddressLine1>
<BuyFromAddressLine2></BuyFromAddressLine2>
<BuyFromCity>Newcastle Upon Type</BuyFromCity>
<BuyFromState>Tyne & Wear</BuyFromState>
<BuyFromCountryLetterCode>GB</BuyFromCountryLetterCode>
<BuyFromPostCode>NE1 4XF</BuyFromPostCode>
<InvoiceDate>2020-03-13T00:00:00</InvoiceDate>
<PostingDate>2020-03-13T00:00:00</PostingDate>
<DueDate>2020-03-30T00:00:00</DueDate>
<Status>Draft</Status>
</PurchaseInvoice>
</PurchaseInvoices>
Lines
The following information can be found within the 'Lines' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| - | Id | string | Optional | Used for matching existing lines |
| - | ExternalId | string | Optional | Stored in Zynk's internal DB and used for matching existing lines |
| - | Sequence | string | Optional | Used for matching existing lines. The next number will be used when creating a new line if not specified |
| No. | ItemId | Guid | Optional | Used for matching existing lines. |
| No. | Item | Item | Optional | Used for looking up and auto creating items |
| - | AccountId | Guid | Optional | The line type will be automatically set to 'Account' if specified |
| - | Account/Number | Guid | Optional | Performs a lookup for the account ID based on number |
| Type | LineType | string | Optional | Can be: Comment, Account, Item, Resource, Fixed Asset, Charge |
| No. | LineObjectNumber | string | Optional | Used for looking up items or accounts by number |
| Description/Comment | Description | string | Optional | |
| Quantity | Quantity | decimal | Required | |
| Unit of Measure Code | UnitOfMeasureId | Guid | Optional | |
| Unit of Measure Code | UnitOfMeasureCode | string | Optional | Performs a lookup for the unit of measure ID based on code |
| Unit Cost | UnitCost | decimal | Required | |
| Line Discount % | DiscountPercent | decimal | Optional | |
| Line Discount % | DiscountAmount | decimal | Optional | |
| - | DiscountAppliedBeforeTax | bool | Read-only | |
| - | AmountExcludingTax | decimal | Read-only | |
| - | TaxCode | string | Optional | |
| - | TaxPercent | decimal | Read-only | |
| - | TotalTaxAmount | decimal | Read-only | |
| Line Amount Incl. VAT | AmountIncludingTax | decimal | Read-only | |
| - | NetAmount | decimal | Read-only | |
| - | NetTaxAmount | decimal | Read-only | |
| - | NetAmountIncludingTax | decimal | Read-only | |
| - | InvoiceDiscountAllocation | decimal | Read-only | |
| - | ExpectedReceiptDate | DateTime | Optional | |
| Inv. Discount Amount Incl. VAT | DiscountAmount | decimal | Optional | |
| Total Excl. VAT | TotalAmountExcludingTax | decimal | Read-only | |
| Total VAT | TotalTaxAmount | decimal | Read-only | |
| Total Incl. VAT | TotalAmountIncludingTax | decimal | Read-only | |
| - | DiscountAppliedBeforeTax | bool | Read-only |
<?xml version="1.0" encoding="utf-8"?>
<PurchaseInvoices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PurchaseInvoice>
<PurchaseInvoiceLines>
<PurchaseInvoiceLine>
<Id>1acbd0e1-3965-ea11-a813-000d3a86fa27-10000</Id>
<ExternalId>TEST-001-1</ExternalId>
<Sequence>10000</Sequence>
<ItemId>abb3e6b3-611d-ea11-bb2d-000d3a4884fc</ItemId>
<Item>
<!-- See Item XML for more details -->
</Item>
<AccountId>f9b2e6b3-611d-ea11-bb2d-000d3a4884fc</AccountId>
<Account>
<Number>10100</Number>
</Account>
<LineType>Item</LineType>
<LineObjectNumber>1896-S</LineObjectNumber>
<Description>ATHENS Desk</Description>
<Quantity>4</Quantity>
<UnitOfMeasureId>2d8c3bdf-549e-ed11-988a-000d3a3885d3</UnitOfMeasureId>
<UnitOfMeasureCode>PCS</UnitOfMeasureCode>
<UnitCost>506.6</UnitCost>
<DiscountAmount>0</DiscountAmount>
<DiscountPercent>0</DiscountPercent>
<DiscountAppliedBeforeTax>false</DiscountAppliedBeforeTax>
<AmountExcludingTax>0</AmountExcludingTax>
<TaxCode>STANDARD</TaxCode>
<TaxPercent>20</TaxPercent>
<TotalTaxAmount>0</TotalTaxAmount>
<AmountIncludingTax>0</AmountIncludingTax>
<NetAmount>1688.67</NetAmount>
<NetTaxAmount>337.73</NetTaxAmount>
<NetAmountIncludingTax>2026.4</NetAmountIncludingTax>
<InvoiceDiscountAllocation>-1688.67</InvoiceDiscountAllocation>
<ExpectedReceiptDate>2020-04-01T00:00:00</ExpectedReceiptDate>
</PurchaseInvoiceLine>
</PurchaseInvoiceLines>
<DiscountAmount>0</DiscountAmount>
<TotalAmountExcludingTax>1688.67</TotalAmountExcludingTax>
<TotalTaxAmount>337.73</TotalTaxAmount>
<TotalAmountIncludingTax>2026.4</TotalAmountIncludingTax>
<DiscountAppliedBeforeTax>false</DiscountAppliedBeforeTax>
</PurchaseInvoice>
</PurchaseInvoices>
Invoice Details
The following information can be found within the 'Invoice Details' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Currency Code | CurrencyId | Guid | Optional | |
| Currency Code | CurrencyCode | string | Optional | Use the 3 letter ISO code |
| Prices Including VAT | PricesIncludeTax | bool | Optional |
<?xml version="1.0" encoding="utf-8"?>
<PurchaseInvoices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PurchaseInvoice>
<CurrencyId>00000000-0000-0000-0000-000000000000</CurrencyId>
<CurrencyCode>GBP</CurrencyCode>
<PricesIncludeTax>true</PricesIncludeTax>
</PurchaseInvoice>
</PurchaseInvoices>
Shipping & Payment
The following information can be found within the 'Shipping & Payment' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Ship-To > Name | ShipToName | string | Optional | |
| Ship-To > Contact | ShipToContact | string | Optional | |
| Ship-To > Address | ShipToAddressLine1 | string | Optional | |
| Ship-To > Address | ShipToAddressLine2 | string | Optional | |
| Ship-To > City | ShipToCity | string | Optional | |
| Ship-To > County | ShipToState | string | Optional | |
| Ship-To > Postcode | ShipToPostCode | string | Optional | |
| Ship-To > Country/Region | ShipToCountry | string | Optional | |
| Pay-to | PayToVendorId | Guid | Optional | |
| Pay-to | PayToVendorNumber | string | Optional | Performs a lookup for the vendor ID based on the number |
| Pay-to | PayToVendor | Vendor | Optional | Used for looking up and auto creating vendors |
| Pay-to > Name | PayToName | string | Read-only | |
| Pay-to > Address | PayToAddressLine1 | string | Read-only | |
| Pay-to > Address | PayToAddressLine2 | string | Read-only | |
| Pay-to > City | PayToCity | string | Read-only | |
| Pay-to > County | PayToState | string | Read-only | |
| Pay-to > Postcode | PayToPostCode | string | Read-only | |
| Pay-to > Country/Region Code | PayToCountry | string | Read-only |
<?xml version="1.0" encoding="utf-8"?>
<PurchaseInvoices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PurchaseInvoice>
<ShipToName>John Smith</ShipToName>
<ShipToContact>John Smith</ShipToContact>
<ShipToAddressLine1>6 Charlotte Square</ShipToAddressLine1>
<ShipToAddressLine2></ShipToAddressLine2>
<ShipToCity>Newcastle Upon Type</ShipToCity>
<ShipToState>Tyne & Wear</ShipToState>
<ShipToCountry>GB</ShipToCountry>
<ShipToPostCode>NE1 4XF</ShipToPostCode>
<PayToVendorId>27db8353-0562-ea11-a812-000d3a86d6af</PayToVendorId>
<PayToVendorNumber>V00010</PayToVendorNumber>
<PayToVendor>
<!-- See Vendor XML for more details -->
</PayToVendor>
<PayToName>Zynk Software</PayToName>
<PayToContact>John Smith</PayToContact>
<PayToAddressLine1>6 Charlotte Square</PayToAddressLine1>
<PayToAddressLine2></PayToAddressLine2>
<PayToCity>Newcastle Upon Type</PayToCity>
<PayToState>Tyne & Wear</PayToState>
<PayToCountry>GB</PayToCountry>
<PayToPostCode>NE1 4XF</PayToPostCode>
</PurchaseInvoice>
</PurchaseInvoices>
Miscellaneous
The following information is not visible within Dynamics 365 Business Central.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| - | ODataETag | string | Optional | Specify the last value to prevent updates if the record has since been modified |
| - | LastModifiedDateTime | DateTime | Read-only |
<?xml version="1.0" encoding="utf-8"?>
<PurchaseInvoices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PurchaseInvoice>
<ODataETag>W/"JzQ0O0tTR0tUQkNUQmg3UzAxK21QbURLTTNFd3kwWjhNL05iQzBtSHpHVlp4b2c9MTswMDsn"</ODataETag>
<LastModifiedDateTime>2020-03-13T14:57:13.203Z</LastModifiedDateTime>
</PurchaseInvoice>
</PurchaseInvoices>