Sage 50 US Sales Order XML

The Import Sales Orders task allows you to create new sales orders, or update existing sales orders in Sage 50 US. We recommend that the ExternalId field be populated by the unique id of the order from the external system, Zynk uses this field to track sales orders already imported to prevent duplicates being created in Sage.

Tasks

XML

Any Sage fields not documented below are not supported with our exports, if there are additional fields you need contact us at [email protected].

Complete import file for creating a sales orders:-

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesOrder Operation="Create">
    <ExternalId>123</ExternalId>
    <CustomerReference>ARMSTRONG</CustomerReference>
    <ShipToAddress>
      <Name>Harding Consulting</Name>
      <Address>
        <Address1>2300 Club Drive</Address1>
        <Address2>Suite A</Address2>
        <City>Norcross</City>
        <State>GA</State>
        <Zip>30093</Zip>
        <Country />
      </Address>
    </ShipToAddress>
    <Date>2015-03-02T00:00:00</Date>
    <ShipByDate>2015-03-02T00:00:00</ShipByDate>
    <ReferenceNumber>10322</ReferenceNumber>
    <IsDropShip>false</IsDropShip>
    <CustomerPurchaseOrderNumber />
    <ShipVia>None</ShipVia>
    <AccountReference>11000-00</AccountReference>
    <SalesTaxCodeReference>GAGWINN</SalesTaxCodeReference>
    <FreightAmount>0</FreightAmount>
    <FreightAccountReference>57500-00</FreightAccountReference>
    <CustomerNote />
    <PrintCustomerNoteAfterLineItems>false</PrintCustomerNoteAfterLineItems>
    <StatementNote>Thank you for choosing Bellwether Garden Supply!</StatementNote>
    <InternalNote />
    <SalesOrderLines>
      <SalesOrderLine>
        <Quantity>2.00</Quantity>
        <InventoryItemReference>BOOK-11010</InventoryItemReference>
        <Description>Bell-Grow Series: Gardening Handbook (Madison)</Description>
        <AccountReference>40000-BK</AccountReference>
        <UnitPrice>29.95</UnitPrice>
        <SalesTaxType>1</SalesTaxType>
  <JobReference>SHARP</JobReference>  
      </SalesOrderLine>
    </SalesOrderLines>
  </SalesOrder>
</ArrayOfSalesOrder>

In each of the following sections most of the XML has been omitted to make the samples easier to read. The sections have been broken up into the various sections of the sales order record as viewed within Sage 50 US.

Operation

When importing orders you can specify whether you would like to create a new order, or update an existing order, via the Operation attribute on each record. It can have one of the following values:

  • Create - Indicates that a new sales order should be created in Sage. If an Operation attribute isn't specified in the XML, it will default to "Create".
  • Update - Indicates that an existing sales order should be updated in Sage. Please note that we don't support updating the 'Customer ID', or the 'SO No' fields, but all other fields can be updated.

In order to update an existing sales order, you must provide at least one of the following fields in your XML to identify which sales order you want to update.

Sage Field XML Field Example Field Type Field Length Input
N/A  ExternalId* 123 string 255 Optional
SO No ReferenceNumber 10322 string 20 Optional
N/A Key* 9683178a-43f4-4c47-b27f-e6e9f45dc8c3  guid - Optional
  • ExternalId* - The sales order must have been imported into Sage by the same Zynk workflow for matching by ExternalId to work.
  • Key* - This is the unique identifier from the Sage database. The value can only be seen in the output from the Export Sales Orders task.
<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesOrder Operation="Update">
    <ExternalId>123</ExternalId>
    <ReferenceNumber>10322</ReferenceNumber>
    <Key>9683178a-43f4-4c47-b27f-e6e9f45dc8c3</Key>
  </SalesOrder>
</ArrayOfSalesOrder>

Specifying The Customer Record

When importing orders you have three options to specify the related customer record: 

  • If you know the customer reference you can specify this in the XML. The customer reference must already exist in Sage.
  • If you are importing customers from a third party system into Sage via Zynk, you can use the AccountExternalId field to provide the ExternalId value that was used at the time the customer was imported into Sage. As long as the customer record has been imported by Zynk, either on a different run or further up in the workflow, Zynk will be able to match the external id to the Sage assigned id. Note any lookups done by Zynk are done per workflow, if you have multiple workflows importing data they will each have their own unique database so lookups will not work between the two.
  • If you know the name or account number of the customer, you can enable the Match Customers On setting on the Import Sales Orders task and specify one or both of these values in the XML.

The following sample shows the different methods.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesOrder>
    <CustomerReference>ALDRED</CustomerReference> <!-- If you know the customer reference -->
    <AccountExternalId>456</AccountExternalId> <!-- If Zynk is importing customers into Sage, and is setting ExternalId to a third party database id of the customer -->
    <Customer>
      <AccountNumber>ALDRED-0001</AccountNumber> <!-- If you know customer's account number -->
      <Name>Aldred</Name> <!-- If you know customer's account name -->
    </Customer>
  </SalesOrder>
</ArrayOfSalesOrder>

The following sample shows how to set the ExternalId when importing a customer into Sage, via the Import Customers task.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfCustomer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Customer>
    <ExternalId>456</ExternalId> <!-- Third party database id of customer -->
    <Id>ALDRED</Id> <!-- Either third party generated or Sage generated customer id -->
  </Customer>
</ArrayOfCustomer>

Main Sales Order Fields

The below will let you specify the main fields required for a sales order record.

Sage Field XML Field Example Field Type Field Length Input
N/A ExternalId 123 string 255 Optional
N/A  AccountExternalId  456 string 255 Optional
Customer ID CustomerReference ARMSTRONG string 20 Required, must exist in Sage as a customer
Name ShipToAddress/Name Harding Consulting  string 39 Optional
Address Line 1 ShipToAddress/Address1 2300 Club Drive string 30 Optional
Address Line 2 ShipToAddress/Address2 Suite A string 30 Optional
City ShipToAddress/City Norcross string 20 Optional
St ShipToAddress/State GA string 2 Optional
Zip ShipToAddress/Zip 30093 string 12 Optional
Country  ShipToAddress/Country  USA string 15 Optional
Date Date 2015-03-02T00:00:00  datetime - Optional, defaults to day of import
Ship by ShipByDate  2015-03-02T00:00:00  datetime  - Optional, defaults to day of import  
SO No ReferenceNumber 10322 string 20 Optional, if provided must be unique, if left out will use the next available number from Sage
Drop ship IsDropShip  false bool - Optional
Customer PO CustomerPurchaseOrderNumber PO-5230  string 20 Optional
Ship via* ShipVia None string 20 Optional
A/R account* AccountReference  11000-00  string 15 Optional
Sales tax* SalesTaxCodeReference  GAGWINN  string 8 Optional
Freight FreightAmount 0 decimal - Optional
Freight account FreightAccountReference  57500-00 string   15 Optional
Customer Note CustomerNote  Leave by the door string 2000 Optional
Print* PrintCustomerNoteAfterLineItems  false bool - Optional
Statement Note StatementNote Leave by the door string 160 Optional
Internal Note InternalNote Leave by the door string 2000 Optional
  • Ship via* - can only be what you have setup in Inventory Item Defaults on the Taxes/Shipping tab
  • A/R account* - can only be what you have setup in Sage under Maintain Chart of Accounts.
  • Sales Tax* - can only be what you have setup in Sage under Maintain -> Sales Taxes
  • Print* - set to false to use print Before Line Items, set to true to use print After Line Items
<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesOrder>
    <ExternalId>123</ExternalId>
    <CustomerReference>ARMSTRONG</CustomerReference>
    <ShipToAddress>
      <Name>Harding Consulting</Name>
      <Address>
        <Address1>2300 Club Drive</Address1>
        <Address2>Suite A</Address2>
        <City>Norcross</City>
        <State>GA</State>
        <Zip>30093</Zip>
        <Country>USA</Country>
      </Address>
    </ShipToAddress>
    <Date>2015-03-02T00:00:00</Date>
    <ShipByDate>2015-03-02T00:00:00</ShipByDate>
    <ReferenceNumber>10322</ReferenceNumber>
    <IsDropShip>false</IsDropShip>
    <CustomerPurchaseOrderNumber>PO-5230</CustomerPurchaseOrderNumber>
    <ShipVia>None</ShipVia>
    <AccountReference>11000-00</AccountReference>
    <SalesTaxCodeReference>GAGWINN</SalesTaxCodeReference>
    <FreightAmount>0</FreightAmount>
    <FreightAccountReference>57500-00</FreightAccountReference>
    <CustomerNote>Leave by the door</CustomerNote>
    <PrintCustomerNoteAfterLineItems>false</PrintCustomerNoteAfterLineItems>
    <StatementNote>Thank you for choosing Bellwether Garden Supply!</StatementNote>
    <InternalNote>Leave by the door</InternalNote>
  </SalesOrder>
</ArrayOfSalesOrder>

Item Line Fields

The below will let you specify the item line fields required for a sales order line. You can provide multiple SalesOrderLine elements as children of the SalesOrderLines element.

When updating an existing order in Sage, the following behaviour applies to the sales order lines:

  • If one or more SalesOrderLine elements are provided, any existing lines will be removed from Sage. The lines you have provided in the XML will then be added to the sales order.
  • If no SalesOrderLine elements are provided, no changes will be made to the lines. Any existing lines in Sage will be preserved.
Sage Field XML Field Example Field Type Field Length Input
Quantity Quantity 2 decimal - Optional
Item InventoryItemReference BOOK-11010 string 20 Optional
Description Description Bell-Grow Series: Gardening Handbook (Madison) string 30 Optional
GL Account* AccountReference 40000-BK string 15 Optional
Unit Price UnitPrice 29.95 decimal - Optional, must be 0 if Quantity is 0
Tax SalesTaxType 1 int - Optional
Job* JobReference SHARP  string 20 Optional
  • GL Account* - can only be what you have setup in Sage under Maintain Chart of Accounts.
  • Job* - can only be what you have setup in Sage under Maintain Jobs.
<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesOrder>
    <SalesOrderLines>
      <SalesOrderLine>
        <Quantity>2.00</Quantity>
        <InventoryItemReference>BOOK-11010</InventoryItemReference>
        <Description>Bell-Grow Series: Gardening Handbook (Madison)</Description>
        <AccountReference>40000-BK</AccountReference>
        <UnitPrice>29.95</UnitPrice>
        <SalesTaxType>1</SalesTaxType>
        <JobReference>SHARP</JobReference>  
      </SalesOrderLine>
    </SalesOrderLines>
  </SalesOrder>
</ArrayOfSalesOrder>