Skip to content

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

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 &amp; 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
Email Email 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 &amp; 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>