Skip to content

Sage 200 Online Sales Order XML

Sales orders are used to represent the sale of goods or services to a customer. They are central to a business and define the terms (price, quantity and times) by which the products or services will be delivered. Further information can be found on the Sage 200 Online Sales Order API Documentation.

Tasks

Identifiers

external_id

Optional (recommended)
To prevent duplicates sales orders being imported into Sage 200 we would recommend to always set the external_id field to a unique id from the source system. When the field is provided it will be stored within Zynk's internal database along with the sales order number assigned by Sage 200.

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

Fields for Download and Upload

customer_id

Dependant (see customer)
Customer record Id, can also be set using customer reference, see customer.

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

document_no

Dependant
Sales order document number. Note: If the SOP setting in Sage 200 Extra is to NOT automatically generate numbers, then this property MUST be set. If the SOP setting in Sage 200 Extra is to automatically generate numbers, or you are using Sage 200 Standard (which doesn't allow you to set this option), then this setting should not be provided.

Type Example XML
string(20) 12345 <document_no>12345</document_no>

document_date

Optional
Sales order document date.

Type Example XML
datetime 2017-06-05T00:00:00 <document_date>2017-06-05T00:00:00</document_date>

customer_document_no

Optional
Customer document number.

Type Example XML
string(30) Order #12345 <customer_document_no>Order #12345</customer_document_no>

use_invoice_address

Optional
True if this order uses the customer invoice address, else False.

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

Available Values

  • true
  • false

settlement_discount_days

Optional
Settlement discount days.

Type Example XML
integer(int16) 0 <settlement_discount_days>0</settlement_discount_days>

settlement_discount_percent

Optional
Settlement discount percent.

Type Example XML
number(decimal 2dp) 0.00 <settlement_discount_percent>0.00</settlement_discount_percent>

document_discount_percent

Optional
Document discount percent value, between -99.99 and 99.99. A negative value is treated as a surcharge (e.g. -10 is a 10% surcharge), and a positive value is treated as a discount.

Type Example XML
number(decimal 2dp) 0.00 <document_discount_percent>0.00</document_discount_percent>

requested_delivery_date

Optional
Requested delivery date.

Type Example XML
datetime 2017-06-10T00:00:00 <requested_delivery_date>2017-06-10T00:00:00</requested_delivery_date>

promised_delivery_date

Optional
Promised delivery date.

Type Example XML
datetime 2017-06-09T00:00:00 <promised_delivery_date>2017-06-09T00:00:00</promised_delivery_date>

Analysis Codes

Optional
Analysis codes are only supported on SOP Orders from version 2016.sp3 (12/09/2017). They 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>

lines

Optional
The sales order lines collection. See Sage 200 Online Sales Order Line XML for full details.

delivery_address

Optional
The sales order delivery address. The <delivery_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>

document_created_by

Optional
The person who created the sales order.

Type Example XML
string(30) John Smith <document_created_by>John Smith</document_created_by>

order_priority

Optional
The order priority.

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

is_triangulated

Optional
Whether this order is triangulated and applies only to an EU customer with a different country code to that set in the company details.

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

Import example only setting the code

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

Fields for Download Only

id

Read Only
Sales order record Id.

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

is_draft

Read Only
Whether it is a draft order.

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

document_status

Read Only
Document status.

Type Example XML
string(20) EnumDocumentStatusLive <document_status>EnumDocumentStatusLive</document_status>

Available Values

  • EnumDocumentStatusLive
  • EnumDocumentStatusOnHold
  • EnumDocumentStatusComplete
  • EnumDocumentStatusDispute
  • EnumDocumentStatusCancelled
  • EnumDocumentStatusDraft
  • EnumDocumentStatusPrinted

exchange_rate

Read Only
Exchange rate.

Type Example XML
number(decimal 6dp) 1.0 <exchange_rate>1.0</exchange_rate>

subtotal_goods_value

Read Only
Goods value (sum of stock items and free text).

Type Example XML
number(decimal 2dp) 40.0 <subtotal_goods_value>40.0</subtotal_goods_value>

subtotal_charge_net_value

Read Only
Charge net value.

Type Example XML
number(decimal 2dp) 40.0 <subtotal_charge_net_value>40.0</subtotal_charge_net_value>

subtotal_charge_tax_value

Read Only
Charge tax value.

Type Example XML
number(decimal 2dp) 40.0 <subtotal_charge_tax_value>40.0</subtotal_charge_tax_value>

subtotal_discount_value

Read Only
Discount value

Type Example XML
number(decimal 2dp) 40.0 <subtotal_discount_value>40.0</subtotal_discount_value>

total_net_value

Read Only
Net value (sum of all line types).

Type Example XML
number(decimal 2dp) 40.0 <total_net_value>40.0</total_net_value>

total_tax_value

Read Only
Tax value.

Type Example XML
number(decimal 2dp) 8.0 <total_tax_value>8.0</total_tax_value>

total_gross_value

Read Only
Gross value.

Type Example XML
number(decimal 2dp) 48.0 <total_gross_value>48.0</total_gross_value>

is_credit_limit_exceeded

Read Only
Whether this order takes the customer over their credit limit.

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

payment_with_order

Read Only
True if there is a payment linked to the order; otherwise false.

Type Example XML
boolean true <payment_with_order>true</payment_with_order>

invoice_payment_with_order_immediately

Read Only
True if the payment linked to the order was invoiced; otherwise false.

Type Example XML
boolean true <invoice_payment_with_order_immediately>true</invoice_payment_with_order_immediately>

payment_value

Read Only
Payment value.

Type Example XML
number(decimal 2dp) 8.0 <payment_value>8.0</payment_value>

payment_reference

Read Only
Payment reference.

Type Example XML
string(20) ZN0129123 <payment_reference>ZN0129123</payment_reference>

payment_method_id

Read Only
Payment method Id.

Type Example XML
integer(int64) 12345 <payment_method_id>12345</payment_method_id>

payment_declared

Read Only
Payment declared.

Type Example XML
number(decimal 2dp) 40.00 <payment_declared>40.00</payment_declared>

payment_undeclared

Read Only
Payment undeclared.

Type Example XML
number(decimal 2dp) 40.00 <payment_undeclared>40.00</payment_undeclared>

declared_payment_remaining

Read Only
Declared payment remaining.

Type Example XML
number(decimal 2dp) 40.00 <declared_payment_remaining>40.00</declared_payment_remaining>

date_time_created

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

Type Example XML
datetime 2017-06-05T15:24:29.44 <date_time_created>2017-06-05T15:24:29.44</date_time_created>

date_time_updated

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

Type Example XML
datetime 2017-06-05T15:24:29.44 <date_time_updated>2017-06-05T15:24:29.44</date_time_updated>

Expandable Fields

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

customer

Dependant (see customer_id)
The sales orders customer. On a download all the related information of the customer will be included in the XML, see Sage 200 Online Customer XML. On an upload you can set the reference of the customer to use for the sales order and Zynk will lookup the correct internal id from Sage.

<customer
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <id>27006</id>
    <date_time_updated>2017-06-05T15:24:29.723</date_time_updated>
    <reference>ZYNK001</reference>
    <name>Zynk Software Ltd.</name>
    <short_name>Zynk</short_name>
    <balance>-480.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>
    <duns_code>424458615</duns_code>
</customer>

Import example only setting the reference

<customer>
    <reference>ZYNK001</reference>
</customer>

Example XML

Minimal Example

<?xml version="1.0" encoding="utf-8"?>
<SalesOrders
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SalesOrder>
        <customer>
            <reference>ZYNK001</reference>
        </customer>
        <lines>
            <line>
                <line_quantity>1</line_quantity>
                <product>
                    <code>TEST001</code>
                </product>
            </line>
        </lines>
    </SalesOrder>
</SalesOrders>

Full Example

<?xml version="1.0" encoding="utf-8"?>
<SalesOrders
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SalesOrder>
        <id>27766</id>
        <external_id>12345</external_id>
        <customer_id>27006</customer_id>
        <document_no>12345</document_no>
        <document_date>2017-06-05T00:00:00</document_date>
        <customer_document_no>Order #12345</customer_document_no>
        <use_invoice_address>false</use_invoice_address>
        <settlement_discount_days>0</settlement_discount_days>
        <settlement_discount_percent>0.00</settlement_discount_percent>
        <requested_delivery_date>2017-06-10T00:00:00</requested_delivery_date>
        <promised_delivery_date>2017-06-09T00:00:00</promised_delivery_date>
        <customer>
            <reference>ZYNK001</reference>
        </customer>
        <delivery_address>
            <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>
                <code>GB</code>
            </address_country_code>
        </delivery_address>
        <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>
        <lines>
            <line>
                <line_number>1</line_number>
                <line_type>EnumLineTypeStandard</line_type>
                <description>Test Product</description>
                <line_quantity>4.0</line_quantity>
                <selling_unit_price>10.0</selling_unit_price>
                <unit_discount_percent>0.0</unit_discount_percent>
                <unit_discount_value>0.0</unit_discount_value>
                <show_on_customer_docs>true</show_on_customer_docs>
                <show_on_picking_list_type>Show</show_on_picking_list_type>
                <product>
                    <code>TEST001</code>
                </product>
                <tax_code>
                    <code>1</code>
                </tax_code>
            </line>
        </lines>
    </SalesOrder>
</SalesOrders>