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:
- If an
<id>
is provided for the customer, the existing customer with this id will be updated. - 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. - 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. - 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.
Export example showing related information
<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.
Export example showing related information
<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.
Export example showing related information
<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.
Export example showing related information
<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.