Sage 200 Online Supplier XML

Suppliers 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. purchase orders, payments, receipts, etc). Further information can be found on the Sage 200 Online Suppliers API Documentation.

Tasks

Identifiers

The logic surrounding inserting/updating suppliers works as follows:

  1. If an <id> is provided for the supplier, the existing supplier with this id will be updated.
  2. If an <external_id> is provided for the supplier, and a match is found in Zynk's truth table, the existing supplier will be updated.
  3. If a <reference> is provided for the supplier, the task will check if a supplier already exists with this reference. If a match is found, the existing supplier will be updated, otherwise a new supplier 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 supplier will be created and given an automatically generated reference.

id

Dependant
The <id> field is the unique internal database id of the supplier. This can be obtained from running a download of suppliers, 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 supplier 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
Supplier name.

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

short_name

Optional
Supplier short name.

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

on_hold

Optional
True if supplier 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 supplier 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 supplier 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 supplier.

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>

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

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>

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>

terms_agreed

True if supplier terms have been agreed else False.

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

order_priority

Order priority.

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

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>

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 suppliers 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
Supplier 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
Supplier account balance.

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

date_time_updated

Read Only
The date and time this entity was last updated (UTC). This field is updated when a supplier 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 suppliers are also included in the downloaded XML, these can also be used to set certain fields on supplier uploads using lookups rather than needing to know the internal id of the related record.

currency

Dependant (see currency_id)
The suppliers 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 supplier 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 suppliers 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 supplier 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 supplier. 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 supplier 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"?>
<Suppliers>
    <Supplier>
        <name>Zynk Software Ltd.</name>
    </Supplier>
</Suppliers>

Full Example

<?xml version="1.0" encoding="utf-8"?>
<Suppliers
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Supplier>
    <external_id>12345</external_id>
    <id>27006</id>
    <date_time_updated>2017-06-02T14:59:04.877</date_time_updated>
    <reference>ZYNK001</reference>
    <name>Zynk Software Ltd.</name>
    <short_name>Zynk</short_name>
    <balance>0.00</balance>
    <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>
    <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>
      <supplier_id>27006</supplier_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>
        <supplier_id>27006</supplier_id>
      </contact>
    </contacts>
  </Supplier>
</Suppliers>

† Available with Sage 200 Extra Online only.