Sage 50 US Sales Invoice XML

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

Tasks

XML

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

Complete import file for creating a sales invoice:-

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesInvoice Operation="Create">
    <ExternalId />
    <ReferenceNumber />
    <Date>2020-03-15T00:00:00</Date>
    <ShipDate>2020-03-15T00:00:00</ShipDate>
    <CustomerReference>HOLLAND</CustomerReference>
    <AccountReference>11000-00</AccountReference>
    <ShipToAddress>
      <Name />
      <Address>
        <Address1 />
        <Address2 />
        <City />
        <State />
        <Zip />
        <Country />
        <SalesTaxCode />
      </Address>
    </ShipToAddress>
    <ShipVia>None</ShipVia>
    <TermsDescription>2% 10, Net 30 Days</TermsDescription>
    <InternalNote />
    <DiscountAmount>10.0000000000000000000</DiscountAmount>
    <CustomerPurchaseOrderNumber />
    <DiscountDate>2020-03-25T00:00:00</DiscountDate>
    <SalesTaxCodeReference>GACOBB</SalesTaxCodeReference>
    <FreightAmount>0</FreightAmount>
    <FreightAccountReference>57500-00</FreightAccountReference>
    <PrintCustomerNoteAfterLineItems>false</PrintCustomerNoteAfterLineItems>
    <CustomerNote />
    <StatementNote />
    <DropShop>false</DropShop>
    <SalesInvoiceOrderLines SalesOrderKey='3ff80f5a-d4c2-4e9c-9151-4ca9e3fa87d1' SalesOrderExternalId="105280" SalesOrderReferenceNumber="29471">
      <SalesInvoiceOrderLine>
        <AccountReference>40000-LS</AccountReference>
        <Description>Group Prep and Cultivation Service</Description>
        <InventoryItemReference>LAND-17700</InventoryItemReference>
        <JobReference>BEATTY</JobReference>
        <Quantity>10.00</Quantity>
        <UnitPrice>30</UnitPrice>
      </SalesInvoiceOrderLine>
    </SalesInvoiceOrderLines>
    <SalesInvoiceLines>
      <SalesInvoiceLine>
        <AccountReference>40000-LS</AccountReference>
        <Description>Weekly Landscaping Service</Description>
        <InventoryItemReference>LAND-17100</InventoryItemReference>
        <JobReference>BEATTY</JobReference>
        <Quantity>4.00</Quantity>
        <UnitPrice>50</UnitPrice>
        <SalesTaxType>2</SalesTaxType>
      </SalesInvoiceLine>
      <SalesInvoiceLine>
        <AccountReference>40000-LS</AccountReference>
        <Description>Group Prep and Cultivation Service</Description>
        <InventoryItemReference>LAND-17700</InventoryItemReference>
        <JobReference>BEATTY</JobReference>
        <Quantity>10.00</Quantity>
        <UnitPrice>30</UnitPrice>
        <SalesTaxType>2</SalesTaxType>
      </SalesInvoiceLine>
    </SalesInvoiceLines>
    <InvoiceType>Invoice</InvoiceType>
    <DateDue>2020-04-14T00:00:00</DateDue>
  </SalesInvoice>
</ArrayOfSalesInvoice>

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 invoice record as viewed within Sage 50 US.

Operation

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

Create - Indicates that a new sales invoice 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 invoice should be updated in Sage. Please note that we don't support updating the 'Customer ID', or the 'Invoice No' fields, but all other fields can be updated.

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

Sage Field	XML Field	Example	Field Type	Field Length	Input
N/A	ExternalId*	123	string	255	Optional
Invoice No	ReferenceNumber	10322	string	20	Optional
N/A	Key*	9683178a-43f4-4c47-b27f-e6e9f45dc8c3	guid	-	Optional

ExternalId* - The sales invoice 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 Invoices task.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesInvoice Operation="Update">
    <ExternalId>123</ExternalId>
    <ReferenceNumber>10322</ReferenceNumber>
    <Key>9683178a-43f4-4c47-b27f-e6e9f45dc8c3</Key>
  </SalesInvoice>
</ArrayOfSalesInvoice>

Specifying The Customer Record

When importing invoices 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 Invoices 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"?>
<ArrayOfSalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesInvoice>
    <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>
  </SalesInvoice>
</ArrayOfSalesInvoice>

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 Invoice Fields

The below will let you specify the main fields required for a sales invoice 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
Invoice Date	Date	2015-03-02T00:00:00	datetime	-	Optional, defaults to day of import
Ship Date	ShipDate	2015-03-03T00:00:00	datetime	-	Optional
Due Date*	DateDue	2015-04-02T00:00:00	datetime	-	Optional
Invoice 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	PO431013	string	20	Optional
Ship via*	ShipVia	None	string	20	Optional
Sales rep*	SalesRepresentativeReference	SPRICHARD	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

Due Date* - if not specified, it will default to the invoice date plus the number of days defined within the default payment terms settings in Sage
Ship via* - can only be what you have setup in Inventory Item Defaults on the Taxes/Shipping tab
Sales rep* - can only be what you have setup in Sage under Maintain Employees & Sales Reps.
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"?>
<ArrayOfSalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesInvoice>
    <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>
    <ShipDate>2015-03-03T00:00:00</ShipDate>
    <DateDue>2015-04-02T00:00:00</DateDue>
    <ReferenceNumber>10322</ReferenceNumber>
    <IsDropShip>false</IsDropShip>
    <CustomerPurchaseOrderNumber>PO431013</CustomerPurchaseOrderNumber>
    <ShipVia>None</ShipVia>
    <SalesRepresentativeReference>SPRICHARD</SalesRepresentativeReference>
    <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>
  </SalesInvoice>
</ArrayOfSalesInvoice>

Terms Fields

The below will let you specify the terms fields for a sales invoice record.

Sage Field	XML Field	Example	Field Type	Field Length	Input
Discount Amount	DiscountAmount	1.00	decimal	15	Optional
Discount Date	DiscountDate	2015-03-25T00:00:00	string	15	Optional
Displayed Terms	TermsDescription	2% 10, Net 30 Days	string	2000	Optional

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SalesInvoice>
    <DiscountAmount>1.00</DiscountAmount>
    <DiscountDate>2015-03-25T00:00:00</DiscountDate>
    <TermsDescription>2% 10, Net 30 Days</TermsDescription>
  </SalesInvoice>
</ArrayOfSalesInvoice>

Apply To Sales Order Line Fields

The below will let you specify the 'apply to sales order' line item fields required for a sales invoice. You can provide multiple SalesInvoiceOrderLine elements as children of the SalesInvoiceOrderLines element.

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

If one or more SalesInvoiceOrderLine elements are provided, any existing lines will be removed from the 'Apply To Sales Order' tab in Sage. The lines you have provided in the XML will then be added to the 'Apply To Sales Order' tab.
If no SalesInvoiceOrderLine 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
SO*	@SalesOrderKey	3ff80f5a-d4c2-4e9c-9151-4ca9e3fa87d1	guid	-	Dependant
SO*	@SalesOrderExternalId	105280	string	255	Dependant
SO*	@SalesOrderReferenceNumber	29471	string	20	Dependant
Item	InventoryItemReference	LAND-17700	string	20	Optional
Received	Quantity	10.00	decimal	-	Optional
Description	Description	Group Prep and Cultivation Service	string	30	Optional
GL Account*	AccountReference	40000-LS	string	15	Optional
Unit Price	UnitPrice	30	decimal	-	Optional, must be 0 if Quantity is 0
Job*	JobReference	BEATTY	string	20	Optional

SO* - At least one of the following attributes must be specified to identify which sales order the lines relate to: SalesOrderKey, SalesOrderExternalId, SalesOrderReferenceNumber.
Job* - can only be what you have setup in Sage under Maintain Jobs.
GL Account* - can only be what you have setup in Sage under Maintain Chart of Accounts.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesInvoice>
  <SalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SalesInvoiceOrderLines SalesOrderKey='3ff80f5a-d4c2-4e9c-9151-4ca9e3fa87d1' SalesOrderExternalId="105280" SalesOrderReferenceNumber="29471">
      <SalesInvoiceOrderLine>
        <InventoryItemReference>LAND-17700</InventoryItemReference>
        <Quantity>10.00</Quantity>
        <Description>Group Prep and Cultivation Service</Description>
        <AccountReference>40000-LS</AccountReference>
        <UnitPrice>30</UnitPrice>
        <JobReference>BEATTY</JobReference>
      </SalesInvoiceOrderLine>
    </SalesInvoiceOrderLines>
  </SalesInvoice>
</ArrayOfSalesInvoice>

Apply To Sales Line Fields

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

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

If one or more SalesInvoiceLine elements are provided, any existing lines will be removed from the 'Apply to Sales Line' tab in Sage. The lines you have provided in the XML will then be added to the 'Apply to Sales Line' tab.
If no SalesInvoiceLine 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	1	decimal	-	Optional
Item	InventoryItemReference	FERT-16160	string	20	Optional
Description	Description	Lawn and Turf Care Service	string	30	Optional
Unit Price	UnitPrice	9.99	decimal	-	Optional, must be 0 if Quantity is 0
Tax	SalesTaxType	1	int	-	Optional
Job*	JobReference	SHARP	string	20	Optional
GL Account*	AccountReference	40000-LS	string	15	Optional

Job* - can only be what you have setup in Sage under Maintain Jobs.
GL Account* - can only be what you have setup in Sage under Maintain Chart of Accounts.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfSalesInvoice>
  <SalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SalesInvoiceLines>
      <SalesInvoiceLine>
        <Quantity>1</Quantity>
        <InventoryItemReference>FERT-16160</InventoryItemReference>
        <Description>Lawn and Turf Care Service</Description>
        <UnitPrice>9.99</UnitPrice>
        <SalesTaxType>1</SalesTaxType>
        <JobReference>SHARP</JobReference>
        <AccountReference>40000-LS</AccountReference>
      </SalesInvoiceLine>
    </SalesInvoiceLines>
  </SalesInvoice>
</ArrayOfSalesInvoice>