Skip to content

Sage 200 Online Customer XML

Customers are one of the most important entities within Sage 200 as they are associated with many important resources within the application and underpin most of the main features (e.g. sales orders, payment receipts, etc). Further information can be found on the Sage 200 Online Customers API Documentation.

Tasks

Identifiers

The logic surrounding inserting/updating customers works as follows:

  1. If an <id> is provided for the customer, the existing customer with this id will be updated.
  2. If an <external_id> is provided for the customer, and a match is found in Zynk's truth table, the existing customer will be updated.
  3. If a <reference> is provided for the customer, the task will check if a customer already exists with this reference. If a match is found, the existing customer will be updated, otherwise a new customer will be created and given the reference specified.
  4. If none of the above conditions are fulfilled, and the 'Auto Generate References' setting is enabled on the task, a new customer will be created and given an automatically generated reference.

id

Dependant
The <id> field is the unique internal database id of the customer. This can be obtained from running a download of customers, or from the response of an upload.

Type Example XML
integer(int64) 27006 <id>27006</id>

external_id

Optional (recommended)
The <external_id> field is used within Zynk to match records already processed. If it is provided Zynk will store the external_id along with the reference in its internal database.

Type Example XML
string(255) 12345 <external_id>12345</external_id>

reference

Dependant
The <reference> field is the customer account reference as shown with the Sage 200 Online interface. This can either be generated automatically if the setting is enabled within Sage, or Zynk can generate one based on the settings setup on the task.

Type Example XML
string(8) ZYNK001 <reference>ZYNK001</reference>

Fields for Download and Upload

name

Required
Customer name.

Type Example XML
string(60) Zynk Software Ltd. <name>Zynk Software Ltd.</name>

short_name

Optional
Customer short name.

Type Example XML
string(8) Zynk <short_name>Zynk</short_name>

on_hold

Optional
True if customer account is on hold, else False.

Type Example XML
boolean false <on_hold>false</on_hold>

Available Values

  • true
  • false

account_status_type

Optional
The status of the customer account.

Type Example XML
string(20) AccountStatusActive <account_status_type>AccountStatusActive</account_status_type>

Available Values

  • AccountStatusActive
  • AccountStatusHidden

currency_id

Dependant (see currency)
Currency record Id, can also be set using currency ISO code, see currency.

Type Example XML
integer(int64) 3 <currency_id>3</currency_id>

exchange_rate_type

Optional
The type of exchange rate used on the customer account.

Type Example XML
string(20) ExchangeRateSingle <exchange_rate_type>ExchangeRateSingle</exchange_rate_type>

Available Values

  • ExchangeRateSingle
  • ExchangeRatePeriod
  • ExchangeRateBoth

telephone_country_code †

Optional
Telephone country code.

Type Example XML
string(5) +44 <telephone_country_code>+44</telephone_country_code>

telephone_area_code †

Optional
Telephone area code.

Type Example XML
string(20) 191 <telephone_area_code>191</telephone_area_code>

telephone_subscriber_number †

Optional
Telephone subscriber number.

Type Example XML
string(200) 303 7279 <telephone_subscriber_number>303 7279</telephone_subscriber_number>

fax_country_code

Optional
Fax country code.

Type Example XML
string(5) +44 <fax_country_code>+44</fax_country_code>

fax_area_code

Optional
Fax area code.

Type Example XML
string(20) 845 <fax_area_code>845</fax_area_code>

fax_subscriber_number

Optional
Fax subscriber number.

Type Example XML
string(200) 123 2920 <fax_subscriber_number>123 2920</fax_subscriber_number>

website

Optional
Website address.

Type Example XML
string(200) http://zynk.com <website>http://zynk.com</website>

credit_limit

Optional
Credit limit for the customer.

Type Example XML
number(decimal 2dp) 10000 <credit_limit>10000</credit_limit>

country_code_id

Dependant (see country_code)
Country code record Id, can also be set using country code, see country_code.

Type Example XML
integer(int64) 13 <country_code_id>13</country_code_id>

default_tax_code_id

Dependant (see default_tax_code)
Default tax code record Id, can also be set using tax code, see default_tax_code.

Type Example XML
integer(int64) 2 <default_tax_code_id>2</default_tax_code_id>

vat_number

Optional
VAT registration number.

Type Example XML
string(30) 796 5763 59 <vat_number>796 5763 59</vat_number>

duns_code

DUNS number.

Type Example XML
string(9) 424458615 <duns_code>424458615</duns_code>

account_type

Optional
The account type is used to decide how transactions are stored on individual accounts.

Type Example XML
string(20) TradingAccountTypeBalanceForward <account_type>TradingAccountTypeBalanceForward</account_type>

Available Values

  • TradingAccountTypeBalanceForward
  • TradingAccountTypeOpenItem
  • TradingAccountTypeAutoAllocation

early_settlement_discount_percent

Optional
The discount percentage offered by suppliers.

Type Example XML
number(decimal 2dp) 10 <early_settlement_discount_percent>10</early_settlement_discount_percent>

early_settlement_discount_days

Optional
The number of days an invoice must be paid within to qualify for the discount.

Type Example XML
integer(int16) 7 <early_settlement_discount_days>7</early_settlement_discount_days>

payment_terms_days

Optional
The number of days which, together with the payment terms basis, determines the due date for invoices.

Type Example XML
integer(int16) 30 <payment_terms_days>30</payment_terms_days>

payment_terms_basis

Optional
The payment terms which, together with the payment terms (days), determines the due date of invoices

Type Example XML
string(20) PaymentDueFromCalendarMonth <payment_terms_basis>PaymentDueFromCalendarMonth</payment_terms_basis>

Available Values

  • PaymentDueFromCalendarMonth
  • PaymentDueFromStartOfMonth
  • PaymentDueFromEndOfMonth
  • PaymentDueFromDocumentDate

terms_agreed

True if supplier terms have been agreed else False.

Type Example XML
boolean() true <terms_agreed>true</terms_agreed>

credit_bureau_id

Credit bureau record Id.

Type Example XML
integer(int64) 1 <credit_bureau_id>1</credit_bureau_id>

credit_position_id

Credit position record Id.

Type Example XML
integer(int64) 1 <credit_position_id>1</credit_position_id>

finance_charge_id

Finance charge record Id. (Sage 200 Professional only).

Type Example XML
integer(int64) 1 <finance_charge_id>1</finance_charge_id>

trading_terms

Trading terms.

Type Example XML
string(30) Net 30 Days <trading_terms>Net 30 Days</trading_terms>

credit_reference

Credit reference.

Type Example XML
string(60) DFW54363 <credit_reference>DFW54363</credit_reference>

account_opened

The date the account was opened.

Type Example XML
string(date-time) 2023-01-22T00:00:00 <account_opened>2023-01-22T00:00:00</account_opened>

last_credit_review

The date of the last credit review.

Type Example XML
string(date-time) 2023-01-22T00:00:00 <last_credit_review>2023-01-22T00:00:00</last_credit_review>

next_credit_review

The date of the next credit review.

Type Example XML
string(date-time) 2023-01-22T00:00:00 <next_credit_review>2023-01-22T00:00:00</next_credit_review>

application_date

The application date.

Type Example XML
string(date-time) 2023-01-22T00:00:00 <application_date>2023-01-22T00:00:00</application_date>

date_received

The date received.

Type Example XML
string(date-time) 2023-01-22T00:00:00 <date_received>2023-01-22T00:00:00</date_received>

office_type

The type of office (Sage 200 Professional only).

Type Example XML
string(20) 2023-01-22T00:00:00 <office_type>Independent</office_type>

Available Values

  • Independent
  • Branch
  • HeadOffice
  • IndependentNoStatement
  • HeadOfficeNoStatement

associated_head_office_id

Associated head office Id (Sage 200 Professional only).

Type Example XML
integer(int64) 1 <associated_head_office_id>1</associated_head_office_id>

produce_statements_for_customer

True if statements are to be produced else False (Sage 200 Professional only)

Type Example XML
boolean() false <produce_statements_for_customer>false</produce_statements_for_customer>

is_head_office_with_branches

True if customer is a Head Office with associated branches; otherwise False (Sage 200 Professional only).

Type Example XML
boolean() false <is_head_office_with_branches>false</is_head_office_with_branches>

use_consolidated_billing

True if consolidated billing is to be used else False (Sage 200 Professional only)

Type Example XML
boolean() false <use_consolidated_billing>false</use_consolidated_billing>

order_priority

Order priority.

Type Example XML
string(1) A <order_priority>A</order_priority>

use_tax_code_as_default

True if tax code is used as the order and invoice default else False.

Type Example XML
boolean() false <use_tax_code_as_default>false</use_tax_code_as_default>

months_to_keep_transactions

The number of months to keep transactions.

Type Example XML
integer(int16) 36 <months_to_keep_transactions>36</months_to_keep_transactions>

default_nominal_code_reference

Default nominal code reference.

Type Example XML
string(8) 5000 <default_nominal_code_reference>5000</default_nominal_code_reference>

default_nominal_code_cost_centre

Default nominal code cost centre.

Type Example XML
string(3) COS <default_nominal_code_cost_centre>COS</default_nominal_code_cost_centre>

default_nominal_code_department

Default nominal code department.

Type Example XML
string(3) DEP <default_nominal_code_department>DEP</default_nominal_code_department>

invoice_discount_percent

Invoice discount percentage for the customer.

Type Example XML
number(decimal 2dp) 10.00 <invoice_discount_percent>10.00</invoice_discount_percent>

invoice_line_discount_percent

Invoice line discount percentage for the customer.

Type Example XML
number(decimal 2dp) 10.00 <invoice_line_discount_percent>10.00</invoice_line_discount_percent>

customer_discount_group_id

Customer discount group id for the customer.

Type Example XML
integer(int64) 1 <customer_discount_group_id>1</customer_discount_group_id>

order_value_discount_id

Order value discount id for the customer.

Type Example XML
integer(int64) 1 <order_value_discount_id>1</order_value_discount_id>

price_band_id

Price band id for the customer.

Type Example XML
integer(int64) 1 <price_band_id>1</price_band_id>

Analysis Codes

Optional
Analysis codes are numbered from 1 to 5 (or 1 to 20 if you are using Sage 200 Professional), and can be specified in the XML using <analysis_code_X>, where X is the analysis code number.

Type Example XML
string(60) North <analysis_code_1>North</analysis_code_1>

main_address

Optional
The customers main address. The <main_address> node is an object which contains the address fields, all of following fields must be inside the node, see full example XML below.

address_1

Optional
Address line 1.

Type Example XML
string(60) i6 <address_1>i6</address_1>

address_2

Optional
Address line 2.

Type Example XML
string(60) 6 - 8 Charlotte Square <address_2>6 - 8 Charlotte Square</address_2>

address_3

Optional
Address line 3.

Type Example XML
string(60) <address_3></address_3>

address_4

Optional
Address line 4.

Type Example XML
string(60) <address_4></address_4>

city

Optional
City.

Type Example XML
string(60) <city>Newcastle</city>

county

Optional
County.

Type Example XML
string(60) Tyne and Wear <county>Tyne and Wear</county>

postcode

Optional
Postcode.

Type Example XML
string(10) NE1 4XF <postcode>NE1 4XF</postcode>

address_country_code_id

Dependant (see address_country_code)
Country code Id, can also be set using country code, see address_country_code.

Type Example XML
integer(int64) 13 <address_country_code_id>13</address_country_code_id>

address_country_code

Dependant (see address_country_code_id)
The address country code. On a download all the related information of the address country code will be included in the XML, see Sage 200 Online Country Code XML. On an upload you can set the code of the country to use for the address and Zynk will lookup the correct internal id from Sage.

<address_country_code>
    <id>13</id>
    <date_time_updated>2015-10-30T22:33:16.67</date_time_updated>
    <name>Great Britain</name>
    <code>GB</code>
    <eu_member>true</eu_member>
</address_country_code>

Import example only setting the code

<address_country_code>
    <code>GB</code>
</address_country_code>

contacts

Optional
Customer contacts. Note Sage 200 Standard Online only supports a single collection, so whilst the contact is in a collection in the XML it is invalid for more than one to be provided. Only the default contact will be updated using this task. See Sage 200 Online Contact XML for full details.

Fields for Download Only

balance

Read Only
Customer account balance.

Type Example XML
number(decimal 2dp) 1000 <balance>1000<balance/>

average_time_to_pay

Read Only
The customer average time to pay.

Type Example XML
integer(int32) 10 <average_time_to_pay>10<average_time_to_pay/>

value_of_current_orders_in_sop

Read Only
Value of current sales orders for this customer.

Type Example XML
number(decimal 2dp) 1000 <value_of_current_orders_in_sop>1000<value_of_current_orders_in_sop/>

date_finance_charge_last_run

Read Only
Date finance charge last run for this customer.

Type Example XML
string(date-time) 2023-01-22T00:00:00 <date_finance_charge_last_run>2023-01-22T00:00:00<date_finance_charge_last_run/>

date_time_created

Read Only
The date and time this entity was created (UTC).

Type Example XML
string(date-time) 2017-06-02T08:19:00.147 <date_time_created>2017-06-02T08:19:00.147</date_time_created>

date_time_updated

Read Only
The date and time this entity was last updated (UTC). This field is updated when a customer is uploaded using Zynk as well as when using the Sage 200 Online interface.

Type Example XML
string(date-time) 2017-06-02T08:19:00.147 <date_time_updated>2017-06-02T08:19:00.147</date_time_updated>

Expandable Fields

Related information linked to customers are also included in the downloaded XML, these can also be used to set certain fields on customer uploads using lookups rather than needing to know the internal id of the related record.

currency

Dependant (see currency_id)
The customers currency. On a download all the related information of the currency will be included in the XML, see Sage 200 Online Currency XML. On an upload you can set the code of the currency to use for the customer and Zynk will lookup the correct internal id from Sage.

<currency>
    <id>1</id>
    <date_time_updated>2016-07-08T09:28:40.9</date_time_updated>
    <symbol>£</symbol>
    <name>Pound Sterling</name>
    <core_currency_rate>1.000000</core_currency_rate>
    <euro_currency_rate>0.860000</euro_currency_rate>
    <currency_iso_code_id>49</currency_iso_code_id>
    <is_base_currency>true</is_base_currency>
    <is_euro_currency>false</is_euro_currency>
    <currency_iso_code>
        <id>49</id>
        <date_time_updated>2015-10-30T22:33:17.707</date_time_updated>
        <code>GBP</code>
        <name>UNITED KINGDOM, Pound Sterling</name>
    </currency_iso_code>
</currency>

Import example only setting the code

<currency>
    <currency_iso_code>
        <code>GBP</code>
    </currency_iso_code>
</currency>

country_code

Dependant (see country_code_id)
The customers country code. On a download all the related information of the country code will be included in the XML, see Sage 200 Online Country Code XML. On an upload you can set the code of the country to use for the customer and Zynk will lookup the correct internal id from Sage.

<country_code>
    <id>13</id>
    <date_time_updated>2015-10-30T22:33:16.67</date_time_updated>
    <name>Great Britain</name>
    <code>GB</code>
    <eu_member>true</eu_member>
</country_code>

Import example only setting the code

<country_code>
    <code>GB</code>
</country_code>

default_tax_code

Dependant (see default_tax_code_id)
The default tax code to be used in transactions for the customer. On a download all the related information of the tax code will be included in the XML. On an upload you can set the code of the tax rate to use for the customer and Zynk will lookup the correct internal id from Sage.

<default_tax_code>
    <id>2</id>
    <date_time_updated>2015-10-30T22:33:16.473</date_time_updated>
    <code>1</code>
    <name>Standard Rate</name>
    <tax_rate>20.00</tax_rate>
</default_tax_code>

Import example only setting the code

<default_tax_code>
    <code>1</code>
</default_tax_code>

Example XML

Minimal Example

<?xml version="1.0" encoding="utf-8"?>
<Customers>
    <Customer>
        <name>Zynk Software Ltd.</name>
    </Customer>
</Customers>

Full Example

<?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>
    <external_id>12345</external_id>
    <id>27006</id>
    <date_time_updated>2017-06-02T14:59:04.877</date_time_updated>
    <date_time_created>2017-06-02T14:59:04.877</date_time_created>
    <reference>ZYNK001</reference>
    <name>Zynk Software Ltd.</name>
    <short_name>Zynk</short_name>
    <on_hold>false</on_hold>
    <account_status_type>AccountStatusActive</account_status_type>
    <currency_id>1</currency_id>
    <exchange_rate_type>ExchangeRateSingle</exchange_rate_type>
    <telephone_country_code>+44</telephone_country_code>
    <telephone_area_code>191</telephone_area_code>
    <telephone_subscriber_number>303 7279</telephone_subscriber_number>
    <fax_country_code>+44</fax_country_code>
    <fax_area_code>845</fax_area_code>
    <fax_subscriber_number>123 2920</fax_subscriber_number>
    <website>http://zynk.com</website>
    <credit_limit>10000.00</credit_limit>
    <country_code_id>13</country_code_id>
    <default_tax_code_id>2</default_tax_code_id>
    <vat_number>796 5763 59</vat_number>
    <duns_code>424458615</duns_code>
    <account_type>TradingAccountTypeBalanceForward</account_type>
    <early_settlement_discount_percent>10</early_settlement_discount_percent>
    <early_settlement_discount_days>7</early_settlement_discount_days>
    <payment_terms_days>30</payment_terms_days>
    <payment_terms_basis>PaymentDueFromCalendarMonth</payment_terms_basis>
    <terms_agreed>true</terms_agreed>
    <credit_bureau_id>1</credit_bureau_id>
    <credit_position_id>1</credit_position_id>
    <finance_charge_id>1</finance_charge_id>
    <trading_terms>Net 30 Days</trading_terms>
    <credit_reference>DFW54363</credit_reference>
    <account_opened>2023-01-22T00:00:00</account_opened>
    <last_credit_review>2023-01-22T00:00:00</last_credit_review>
    <next_credit_review>2023-01-22T00:00:00</next_credit_review>
    <application_date>2023-01-22T00:00:00</application_date>
    <date_received>2023-01-22T00:00:00</date_received>
    <office_type>Independent</office_type>
    <associated_head_office_id>1</associated_head_office_id>
    <produce_statements_for_customer>false</produce_statements_for_customer>
    <is_head_office_with_branches>false</is_head_office_with_branches>
    <use_consolidated_billing>false</use_consolidated_billing>
    <order_priority>A</order_priority>
    <use_tax_code_as_default>false</use_tax_code_as_default>
    <months_to_keep_transactions>36</months_to_keep_transactions>
    <default_nominal_code_reference>5000</default_nominal_code_reference>
    <default_nominal_code_cost_centre>COS</default_nominal_code_cost_centre>
    <default_nominal_code_department>DEP</default_nominal_code_department>
    <invoice_discount_percent>10.00</invoice_discount_percent>
    <invoice_line_discount_percent>10.00</invoice_line_discount_percent>
    <customer_discount_group_id>1</customer_discount_group_id>
    <order_value_discount_id>1</order_value_discount_id>
    <price_band_id>1</price_band_id>
    <analysis_code_1>North</analysis_code_1>
    <analysis_code_2>Software</analysis_code_2>
    <analysis_code_3>01/01/2005</analysis_code_3>
    <analysis_code_4>10</analysis_code_4>
    <analysis_code_5>true</analysis_code_5>
    <country_code>
      <id>13</id>
      <date_time_updated>2015-10-30T22:33:16.67</date_time_updated>
      <name>Great Britain</name>
      <code>GB</code>
      <eu_member>true</eu_member>
    </country_code>
    <currency>
      <id>1</id>
      <date_time_updated>2016-07-08T09:28:40.9</date_time_updated>
      <symbol>£</symbol>
      <name>Pound Sterling</name>
      <core_currency_rate>1.000000</core_currency_rate>
      <euro_currency_rate>0.860000</euro_currency_rate>
      <currency_iso_code_id>49</currency_iso_code_id>
      <is_base_currency>true</is_base_currency>
      <is_euro_currency>false</is_euro_currency>
      <currency_iso_code>
        <id>49</id>
        <date_time_updated>2015-10-30T22:33:17.707</date_time_updated>
        <code>GBP</code>
        <name>UNITED KINGDOM, Pound Sterling</name>
      </currency_iso_code>
    </currency>
    <default_tax_code>
      <id>2</id>
      <date_time_updated>2015-10-30T22:33:16.473</date_time_updated>
      <code>1</code>
      <name>Standard Rate</name>
      <tax_rate>20.00</tax_rate>
    </default_tax_code>
    <main_address>
      <id>27007</id>
      <date_time_updated>2017-06-02T11:36:13.097</date_time_updated>
      <address_1>i6</address_1>
      <address_2>6 - 8 Charlotte Square</address_2>
      <address_3 />
      <address_4 />
      <city>Newcastle</city>
      <county>Tyne and Wear</county>
      <postcode>NE1 4XF</postcode>
      <address_country_code_id>13</address_country_code_id>
      <address_country_code>
        <id>13</id>
        <date_time_updated>2015-10-30T22:33:16.67</date_time_updated>
        <name>Great Britain</name>
        <code>GB</code>
        <eu_member>true</eu_member>
      </address_country_code>
      <customer_id>27006</customer_id>
    </main_address>
    <contacts>
      <contact>
        <id>27008</id>
        <salutation_id>1</salutation_id>
        <name>Mr. Andrew Bryan Snape</name>
        <first_name>Andrew</first_name>
        <middle_name>Bryan</middle_name>
        <last_name>Snape</last_name>
        <is_default>true</is_default>
        <default_telephone>+44 191 303 7279</default_telephone>
        <default_email>[email protected]</default_email>
        <salutation>
          <id>1</id>
          <date_time_updated>2015-10-30T22:33:25.81</date_time_updated>
          <code>Mr.</code>
          <description>Mr.</description>
          <is_default>false</is_default>
        </salutation>
        <date_time_updated>2017-06-02T14:59:04.893</date_time_updated>
        <customer_id>27006</customer_id>
      </contact>
    </contacts>
    <balance>0.00</balance>
    <average_time_to_pay>10<average_time_to_pay/>
    <value_of_current_orders_in_sop>1000<value_of_current_orders_in_sop/>
    <date_finance_charge_last_run>2023-01-22T00:00:00<date_finance_charge_last_run/>
  </Customer>
</Customers>

† Available with Sage 200 Extra Online only.