Dynamics 365 Business Central Customer XML
The XML format documented here is used for both the import and export of customer records in Dynamics 365 Business Central.
We recommend that the ExternalId field be populated with the unique ID of the customers from the external system, Zynk uses this field to track customers already imported to prevent duplicates being created in Dynamics 365 Business Central.
Tasks
- Exporting Customers from Dynamics 365 Business Central
- Importing Customers 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 Customer File:
<?xml version="1.0" encoding="utf-8"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Customer>
<Id>d4f4fd40-34bc-ed11-9a88-6045bd0cf992</Id>
<ODataETag>W/"JzE2OzIxOTA3ODUwMDk0MDE5OTUxOzAwOyc="</ODataETag>
<Number>C00020</Number>
<DisplayName>Zynk Software</DisplayName>
<Type>Company</Type>
<AddressLine1>Office 16</AddressLine1>
<AddressLine2>6 Charlotte Square</AddressLine2>
<City>Newcastle</City>
<State>Tyne & Wear</State>
<Country>GB</Country>
<PostalCode>NE1 4XF</PostalCode>
<PhoneNumber />
<Email>[email protected]</Email>
<Website>www.zynk.com</Website>
<TaxLiable>false</TaxLiable>
<TaxAreaId>248e3bdf-549e-ed11-988a-000d3a3885d3</TaxAreaId>
<TaxAreaDisplayName>Domestic customers and vendors</TaxAreaDisplayName>
<TaxRegistrationNumber />
<CurrencyId>00000000-0000-0000-0000-000000000000</CurrencyId>
<CurrencyCode>GBP</CurrencyCode>
<PaymentTermsId>fa97d7da-549e-ed11-988a-000d3a3885d3</PaymentTermsId>
<ShipmentMethodId>ae98d7da-549e-ed11-988a-000d3a3885d3</ShipmentMethodId>
<PaymentMethodId>c58d3bdf-549e-ed11-988a-000d3a3885d3</PaymentMethodId>
<Blocked>_x0020_</Blocked>
<LastModifiedDateTime>2023-03-06T15:33:37.68Z</LastModifiedDateTime>
<PaymentTerm>
<Id>fa97d7da-549e-ed11-988a-000d3a3885d3</Id>
<ODataETag>W/"JzIwOzEwODIzMjE3MjE0NjMyMjk4NDMzMTswMDsn"</ODataETag>
<Code>14 DAYS</Code>
<DisplayName>Net 14 days</DisplayName>
<DueDateCalculation>14D</DueDateCalculation>
<DiscountDateCalculation />
<DiscountPercent>0</DiscountPercent>
<CalculateDiscountOnCreditMemos>false</CalculateDiscountOnCreditMemos>
<LastModifiedDateTime>2023-01-27T15:11:51.297Z</LastModifiedDateTime>
</PaymentTerm>
<ShipmentMethod>
<Id>ae98d7da-549e-ed11-988a-000d3a3885d3</Id>
<ODataETag>W/"JzIwOzE0NTM3NDA2NzkzNDMxNzkzNTgxMTswMDsn"</ODataETag>
<Code>CFR</Code>
<DisplayName>Cost and Freight</DisplayName>
<LastModifiedDateTime>2023-01-27T15:11:52.813Z</LastModifiedDateTime>
</ShipmentMethod>
<PaymentMethod>
<Id>c58d3bdf-549e-ed11-988a-000d3a3885d3</Id>
<ODataETag>W/"JzIwOzE0NTM2OTMxODM4MjMzMzgyMjk5MTswMDsn"</ODataETag>
<Code>BANK</Code>
<DisplayName>Bank Transfer</DisplayName>
<LastModifiedDateTime>2023-01-27T15:18:51.923Z</LastModifiedDateTime>
</PaymentMethod>
<CustomerFinancialDetail>
<Id>d4f4fd40-34bc-ed11-9a88-6045bd0cf992</Id>
<ODataETag>W/"JzE5OzQ2MDk0MTAzMjg4ODI5ODkxNTkxOzAwOyc="</ODataETag>
<Number>C00020</Number>
<Balance>0</Balance>
<TotalSalesExcludingTax>172.33</TotalSalesExcludingTax>
<OverdueAmount>0</OverdueAmount>
</CustomerFinancialDetail>
<Picture>
<Id>d4f4fd40-34bc-ed11-9a88-6045bd0cf992</Id>
<ODataETag>W/"JzE5OzQ2MDk2MzE0NjIwNTc2NDk5NjQxOzAwOyc="</ODataETag>
<ParentType>Customer</ParentType>
<Width>0</Width>
<Height>0</Height>
<ContentType />
<PictureContentEditLink>https://api.businesscentral.dynamics.com/v2.0/PRODUCTION/api/v2.0/companies(bba482b8-549e-ed11-988a-000d3a3885d3)/customers(d4f4fd40-34bc-ed11-9a88-6045bd0cf992)/picture/pictureContent</PictureContentEditLink>
<PictureContentReadLink>https://api.businesscentral.dynamics.com/v2.0/PRODUCTION/api/v2.0/companies(bba482b8-549e-ed11-988a-000d3a3885d3)/customers(d4f4fd40-34bc-ed11-9a88-6045bd0cf992)/picture/pictureContent</PictureContentReadLink>
<PictureContent><!-- base 64 encoded content here --></PictureContent>
</Picture>
<DefaultDimensions />
<AgedAccountsReceivable>
<ODataETag>W/"JzIwOzE3NjQzMzMxNTE1MTM0Mzg4NTE5MTswMDsn"</ODataETag>
<CustomerId>d4f4fd40-34bc-ed11-9a88-6045bd0cf992</CustomerId>
<CustomerNumber>C00020</CustomerNumber>
<Name>Zynk Software</Name>
<CurrencyCode />
<BalanceDue>0</BalanceDue>
<currentAmount>0</currentAmount>
<Period1Amount>0</Period1Amount>
<Period2Amount>0</Period2Amount>
<Period3Amount>0</Period3Amount>
<agedAsOfDate>2023-03-08T00:00:00</agedAsOfDate>
<periodLengthFilter>30D</periodLengthFilter>
</AgedAccountsReceivable>
<ContactsInformation>
<ContactInformation>
<ODataETag>W/"JzIwOzEyNjQ1NTYxOTY2MDAwMDIwNTgxMTswMDsn"</ODataETag>
<ContactId>d8f4fd40-34bc-ed11-9a88-6045bd0cf992</ContactId>
<ContactNumber>CT000026</ContactNumber>
<ContactName>Zynk Software</ContactName>
<ContactType>Company</ContactType>
<RelatedId>d4f4fd40-34bc-ed11-9a88-6045bd0cf992</RelatedId>
<RelatedType>Customer</RelatedType>
</ContactInformation>
</ContactsInformation>
</Customer>
</Customers>
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 Customers 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 customers |
| - | ExternalId | string | Optional | Stored in Zynk's internal DB and used for matching existing customers |
| No. | Number | string | Optional | Used for matching existing customers. The next number will be used when creating a new customer if not specified |
| Name | DisplayName | string | Required | |
| Balance | CustomerFinancialDetail/ Balance | decimal | Read-only | |
| Balance Due | CustomerFinancialDetail/ OverdueAmount | decimal | Read-only | |
| Total Sales | CustomerFinancialDetail/ TotalSalesExcludingTax | decimal | Read-only | |
| Blocked | Blocked | string | Optional | Set to "All" to block the customer, or blank to unblock |
| LastDateModified | LastModifiedDateTime | DateTime | Read-only | |
| - | Type | string | Optional | Can be "Company" or "Person" |
<?xml version="1.0" encoding="utf-8"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Customer>
<Id>d4f4fd40-34bc-ed11-9a88-6045bd0cf992</Id>
<ExternalId>5230</ExternalId>
<Number>C00020</Number>
<DisplayName>Zynk Software</DisplayName>
<CustomerFinancialDetail>
<Balance>0</Balance>
<OverdueAmount>0</OverdueAmount>
<TotalSalesExcludingTax>0</TotalSalesExcludingTax>
</CustomerFinancialDetail>
<Blocked> </Blocked>
<LastModifiedDateTime>2020-03-09T11:04:32.277Z</LastModifiedDateTime>
<Type>Company</Type>
</Customer>
</Customers>
Address & Contact
The following information can be found within the 'Address & Contact' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Address | AddressLine1 | string | Optional | |
| Address | AddressLine2 | string | Optional | |
| City | City | string | Optional | |
| County | State | string | Optional | |
| Country/Region Code | Country | string | Optional | Use the 2 letter ISO code |
| Postcode | PostalCode | string | Optional | |
| Phone No. | PhoneNumber | string | Optional | |
| string | Optional | |||
| Homepage | Website | string | Optional |
<?xml version="1.0" encoding="utf-8"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Customer>
<AddressLine1>Office 16</AddressLine1>
<AddressLine2>6 Charlotte Square</AddressLine2>
<City>Newcastle</City>
<State>Tyne & Wear</State>
<Country>GB</Country>
<PostalCode>NE1 4XF</PostalCode>
<PhoneNumber>0191 303 2920</PhoneNumber>
<Email>[email protected]</Email>
<Website>www.zynk.com</Website>
</Customer>
</Customers>
Invoicing
The following information can be found within the 'Invoicing' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| VAT Registration No. | TaxRegistrationNumber | string | Optional | |
| Currency Code | CurrencyId | Guid | Optional | |
| Currency Code | CurrencyCode | string | Optional | Performs a lookup for the currency ID based on the 3 letter ISO code |
<?xml version="1.0" encoding="utf-8"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Customer>
<TaxRegistrationNumber>GB111111111</TaxRegistrationNumber>
<CurrencyId>00000000-0000-0000-0000-000000000000</CurrencyId>
<CurrencyCode>GBP</CurrencyCode>
</Customer>
</Customers>
Payment
The following information can be found within the 'Payment' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Payment Terms Code | PaymentTermsId | Guid | Optional | |
| Payment Terms Code | PaymentTerm/Code | string | Optional | Performs a lookup for the payment terms ID based on the code |
| Payment Method Code | PaymentMethodId | Guid | Optional | |
| Payment Method Code | PaymentMethod/Code | string | Optional | Performs a lookup for the payment method ID based on the code |
<?xml version="1.0" encoding="utf-8"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Customer>
<PaymentTermsId>9eb1e6b3-611d-ea11-bb2d-000d3a4884fc</PaymentTermsId>
<PaymentTerm>
<Code>14 DAYS</Code>
</PaymentTerm>
<PaymentMethodId>a314deb9-611d-ea11-bb2d-000d3a4884fc</PaymentMethodId>
<PaymentMethod>
<Code>BANK</Code>
</PaymentMethod>
</Customer>
</Customers>
Shipping
The following information can be found within the 'Shipping' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Shipment Method > Code | ShipmentMethodId | Guid | Optional | |
| Shipment Method > Code | ShipmentMethod/Code | string | Optional | Performs a lookup for the shipment method ID based on the code |
<?xml version="1.0" encoding="utf-8"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Customer>
<ShipmentMethodId>c4b2e6b3-611d-ea11-bb2d-000d3a4884fc</ShipmentMethodId>
<ShipmentMethod>
<Code>CFR</Code>
</ShipmentMethod>
</Customer>
</Customers>
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 |
| - | TaxLiable | bool | Optional | |
| - | TaxAreaId | Guid | Optional | |
| - | TaxAreaDisplayName | string | Optional | Performs a lookup for the tax area ID based on name |
<?xml version="1.0" encoding="utf-8"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Customer>
<ODataETag>W/"JzQ0O3NPT21NalFNYnlTdm9iSzBlRkdVZlltOFRQeXJZSUpzRTQxMHYxeGlJMlE9MTswMDsn"</ODataETag>
<TaxLiable>false</TaxLiable>
<TaxAreaId>0015deb9-611d-ea11-bb2d-000d3a4884fc</TaxAreaId>
<TaxAreaDisplayName>Domestic customers and vendors</TaxAreaDisplayName>
</Customer>
</Customers>