Skip to content

Sage 50 CA Sales Invoice XML

The following tasks use the Sage 50 CA Sales Invoice XML format.

Tasks

XML Overview

Any Sage fields not documented below are not supported with our imports/exports. Examples of where in the XML the fields should appear are shown in the samples below.

Minimal Sales Invoice File

<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices>
  <SalesInvoice>
    <Customer>
      <Name>Zynk Software</Name>
    </Customer>
    <LineItems>
      <LineItem>
        <Quantity>2</Quantity>
        <Description>Computer Repair - No Warranty</Description>
        <Price>5</Price>
      </LineItem>
    </LineItems>
  </SalesInvoice>
</SalesInvoices>

Complete Sales Invoice File

<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices>
  <SalesInvoice>
    <ExternalId>5230</ExternalId>
    <InvoiceNumber>5230</InvoiceNumber>
    <Customer>
      <ExternalId>124</ExternalId>
      <Name>Zynk Software</Name>
      <CurrencyCode>CAD</CurrencyCode>
      <Contact>John Smith</Contact>
      <Street1>i6</Street1>
      <Street2>6-8 Charlotte Square</Street2>
      <City>Newcastle</City>
      <Province>Tyne &amp; Wear</Province>
      <PostalCode>NE1 4XF</PostalCode>
      <Country>Great Britain</Country>
      <Phone1>0191 820 1484</Phone1>
      <Phone2>0191 820 1484</Phone2>
      <Fax>0191 820 1484</Fax>
      <Email>[email protected]</Email>
      <Website>www.zynk.com</Website>
    </Customer>
    <Date>2023-07-27</Date>
    <LinkedDocumentNumber>DO-4</LinkedDocumentNumber>
    <ShippingDate>2023-07-28</ShippingDate>
    <Salesperson>Zan, Yao</Salesperson>
    <ShipFrom>Ontario</ShipFrom>
    <JobSite>Askew Shopping Centre</JobSite>
    <Payment>
      <Method>Cheque</Method>
      <Account>10600</Account>
      <ChequeNumber>123456</ChequeNumber>
    </Payment>
    <CustomerAddress>
      <Address1>Teresa Green</Address1>
      <Address2>i6</Address2>
      <Address3>6-8 Charlotte Square</Address3>
      <Address4>Newcastle, Tyne &amp; Wear  NE1 4XF</Address4>
      <Address5>Great Britain</Address5>
    </CustomerAddress>
    <ShippingAddress>
      <AddressName>&lt;Mailing Address&gt;</AddressName>
      <Address1>Zynk Software</Address1>
      <Address2>John Smith</Address2>
      <Address3>i6</Address3>
      <Address4>6-8 Charlotte Square</Address4>
      <Address5>Newcastle, Tyne &amp; Wear  NE1 4XF</Address5>
      <Address6>Great Britain</Address6>
    </ShippingAddress>
    <LineItems>
      <LineItem>
        <ItemNumber>CR-10</ItemNumber>
        <ItemExternalId>1234</ItemExternalId>
        <Quantity>2</Quantity>
        <Unit>Each</Unit>
        <Description>Computer Repair - No Warranty</Description>
        <BasePrice>5</BasePrice>
        <DiscountPercentage>0</DiscountPercentage>
        <Price>5</Price>
        <Amount>10</Amount>
        <TaxCode>GP</TaxCode>
        <Account>42200</Account>
        <JobSites>
            <JobSite>
                <Site>Askew Shopping Centre</Site>
                <Percentage>50</Percentage>
            </JobSite>
            <JobSite>
                <Site>Basement Renovation</Site>
                <Amount>5</Amount>
            </JobSite>
        </JobSites>
      </LineItem>
    </LineItems>
    <Freight>
      <Amount>2.00</Amount>
      <TaxCode>GP</TaxCode>
      <Tax1Amount>0.10</Tax1Amount>
      <Tax2Amount>0.14</Tax2Amount>
      <JobSites>
        <JobSite>
            <Site>Askew Shopping Centre</Site>
            <Amount>1.12</Amount>
            <Percentage>50</Percentage>
        </JobSite>
      </JobSites>
    </Freight>
    <Terms>
      <DiscountPercentage>2</DiscountPercentage>
      <DiscountDays>30</DiscountDays>
      <NetDays>60</NetDays>
    </Terms>
    <Message>Thank you for your business!</Message>
    <AdditionalInfo>
      <AdditionalDate>2023-07-26</AdditionalDate>
      <AdditionalField>Some additional info</AdditionalField>
    </AdditionalInfo>
    <AttachmentFile>inv-523.pdf</AttachmentFile>
    <AttachmentUrl>https://www.zynk.com</AttachmentUrl>
  </SalesInvoice>
</SalesInvoices>

In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the SalesOrders schema is used below as a reference of where fields should be in the object model.

Header Information

The following fields can be populated at the header level of the sales invoice record.

When importing sales invoices into Sage, we recommend that the ExternalId field be populated by the unique id of the sales invoice from the external system. Zynk uses this field to track sales invoices already imported into Sage, and it can be used in conjunction with the Prevent Reprocessing task setting to prevent duplicate sales invoices being created in Sage.

The customer name field acts as the unique identifier for customers in Sage. The customer can be specified by any of the following methods:

  • Provide the customer name via the Customer/Name element in the XML. If a customer exists in Sage with this name, it will be selected. If not, a one-time customer will be used with the name specified. Alternatively, you can explicitly set the name to <One-time customer> to use a one-time customer.
  • If the customer has been imported into Sage by Zynk before, and an ExternalId value was provided at the time, providing the same Customer/ExternalId value again will allow Zynk to determine the name via our truth table.
  • Use the Customer Match Fields task setting to search Sage for a matching customer based on the value of one or more fields (such as email address or postal code).
Sage Field XML Field  Field Type  Input  Notes
- ExternalId string(255) Optional Provide the ID of the sales invoice from the source system
Invoice No InvoiceNumber string(20) Dependant If auto numbering is not enabled in Sage, you must provide this value
Customer Customer/Id string(255) Optional Used to looked up the customer name in Zynk's truth table
Customer Customer/Name string(52) Required The value can be looked up in Zynk's truth table via the Customer/ExternalId, or the 'Customer Match Fields' task setting
Date Date datetime Optional Will default to the current date if not specified
DO/Contract/Estimate No. LinkedDocumentNumber string(20) Optional
Shipping Date ShippingDate datetime Optional
Salesperson Salesperson string(52) Optional
Ship from ShipFrom string(35) Optional
Job Site JobSite string(52) Optional If specified, you can't set job information at the line level
Payment Method Payment/Method string(30) Optional
Deposit To Payment/Account string(8) Optional
Cheque Payment/ChequeNumber string(20) Optional
Additional Information > Additional Date AdditionalInfo/AdditionalDate datetime Optional
Additional Information > Additional Field AdditionalInfo/AdditionalField string(75) Optional
Attachment > File AttachmentFile string(1023) Optional Can't be specified if AttachmentUrl is provided
Attachment > Internet AttachmentUrl string(1023) Optional Can't be specified if AttachmentFile is provided 
<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices>
  <SalesInvoice>
    <ExternalId>5230</ExternalId>
    <InvoiceNumber>5230</InvoiceNumber>
    <Customer>
      <ExternalId>124</ExternalId>
      <Name>Zynk Software</Name>
    </Customer>
    <Date>2023-07-27</Date>
    <LinkedDocumentNumber>DO-4</LinkedDocumentNumber>
    <ShippingDate>2023-07-28</ShippingDate>
    <Salesperson>Zan, Yao</Salesperson>
    <ShipFrom>Ontario</ShipFrom>
    <JobSite>Askew Shopping Centre</JobSite>
    <Payment>
      <Method>Cheque</Method>
      <Account>10600</Account>
      <ChequeNumber>123456</ChequeNumber>
    </Payment>
    <AdditionalInfo>
      <AdditionalDate>2023-07-26</AdditionalDate>
      <AdditionalField>Some additional info</AdditionalField>
    </AdditionalInfo>
    <AttachmentFile>inv-523.pdf</AttachmentFile>
    <AttachmentUrl>https://www.zynk.com</AttachmentUrl>
  </SalesInvoice>
</SalesInvoices>

Auto Creating Customers

Zynk can automatically create new customers in Sage where they don't already exist. To do this, you must enable the Auto Create Customers task setting, and provide the customer information described below in the XML.

Sage Field XML Field  Field Type  Input  Notes
- Customer/ExternalId string(255) Optional Provide the ID of the customer from the source system
Customer Customer/Name string(52) Required
Currency  Customer/CurrencyCode string(3) Optional  Specify the 3 letter currency ISO code
Contact Customer/Contact string(30) Optional
Street1 Customer/Street1 string(50) Optional
Street2 Customer/Street2 string(50) Optional
City Customer/City string(35) Optional
Province Customer/Province string(20) Optional
PostalCode Customer/PostalCode string(9) Optional
Country Customer/Country string(30) Optional
Phone1 Customer/Phone1 string(25) Optional
Phone2 Customer/Phone2 string(25) Optional
Fax Customer/Fax string(25) Optional
Email Customer/Email string(50) Optional
Website Customer/Website string(50) Optional
Price List Customer/PriceList  string(25) Optional  
<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices>
  <SalesInvoice>
    <Customer>
      <ExternalId>123</ExternalId>
      <Name>Zynk Software</Name>
      <CurrencyCode>CAD</CurrencyCode>
      <Contact>John Smith</Contact>
      <Street1>i6</Street1>
      <Street2>6-8 Charlotte Square</Street2>
      <City>Newcastle</City>
      <Province>Tyne &amp; Wear</Province>
      <PostalCode>NE1 4XF</PostalCode>
      <Country>Great Britain</Country>
      <Phone1>0191 820 1484</Phone1>
      <Phone2>0191 820 1484</Phone2>
      <Fax>0191 820 1484</Fax>
      <Email>[email protected]</Email>
      <Website>www.zynk.com</Website>
      <PriceList>Preferred</PriceList>
    </Customer>
  </SalesInvoice>
</SalesInvoices>

Address Information

The following fields can be populated in the customer address and shipping address sections of the sales invoice record.

If a customer was selected, the customer address will always be set to the address shown on the customers account, and can't be overridden. You can only set the customer address when the invoice is being raised against a one-time customer.

If a customer was selected, and you haven't provided a shipping address, the default shipping address will be picked up automatically from the customer's account. The shipping address can always be overridden.

Sage Field XML Field  Field Type  Input  Notes
Customer Address > Line 1  CustomerAddress/Address1 string(75)  Optional  Can only be populated when the customer is a one-time customer
Customer Address > Line 2  CustomerAddress/Address2  string(75) Optional  Can only be populated when the customer is a one-time customer
Customer Address > Line 3  CustomerAddress/Address3 string(75) Optional Can only be populated when the customer is a one-time customer
Customer Address > Line 4  CustomerAddress/Address4 string(75) Optional Can only be populated when the customer is a one-time customer
Customer Address > Line 5  CustomerAddress/Address5 string(75) Optional Can only be populated when the customer is a one-time customer
Shipping Address ShippingAddress/AddressName string(25) Optional Used to select an existing shipping address from the customer account. Don't specify this if you want to provide the address via the fields below.
Shipping Address > Line 1  ShippingAddress/Address1 string(75)  Optional 
Shipping Address > Line 2  ShippingAddress/Address2  string(75) Optional 
Shipping Address > Line 3  ShippingAddress/Address3 string(75) Optional
Shipping Address > Line 4  ShippingAddress/Address4 string(75) Optional
Shipping Address > Line 5  ShippingAddress/Address5 string(75) Optional
Shipping Address > Line 6  ShippingAddress/Address6 string(75) Optional 
<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices>
  <SalesInvoice>
    <CustomerAddress>
      <Address1>Teresa Green</Address1>
      <Address2>i6</Address2>
      <Address3>6-8 Charlotte Square</Address3>
      <Address4>Newcastle, Tyne &amp; Wear  NE1 4XF</Address4>
      <Address5>Great Britain</Address5>
    </CustomerAddress>
    <ShippingAddress>
      <AddressName>&lt;Mailing Address&gt;</AddressName>
      <Address1>Zynk Software</Address1>
      <Address2>John Smith</Address2>
      <Address3>i6</Address3>
      <Address4>6-8 Charlotte Square</Address4>
      <Address5>Newcastle, Tyne &amp; Wear  NE1 4XF</Address5>
      <Address6>Great Britain</Address6>
    </ShippingAddress>
  </SalesInvoice>
</SalesInvoices>

Line Items

The following fields can be populated at the line level of the sales invoice record.

Sage Field XML Field  Field Type  Input  Notes
Item Number  ItemNumber string(52)  Optional 
-  ItemExternalId string(255)  Optional  Can be used to look up the ItemNumber, if the item was created via the Import Items task, and an ExternalId was specified.
Quantity Quantity  double  Dependant  At least one of the following must be provided: Quantity, Ordered or BackOrdered
Order Ordered  double  Dependant  At least one of the following must be provided: Quantity, Ordered or BackOrdered
Back Order BackOrdered  double  Dependant  At least one of the following must be provided: Quantity, Ordered or BackOrdered
Unit Unit  string(15) Optional 
Item Description Description  string(75)  Optional If not specified, will default to the description from the item
Base Price BasePrice  double Optional 
Discount DiscountPercentage  double Optional 
Price  Price  double  Optional If not specified, will default to the price from the item
Amount Amount  double  Optional  If not specified, will default to the price times the quantity
Tax TaxCode string(12) Optional 
Account Account  string(8) Optional 
Job Sites > Job Site JobSites/JobSite/Site double Optional 
Job Sites > Amount JobSites/JobSite/Amount double Optional 
Job Sites > Percentage JobSites/JobSite/Percentage double Optional  
<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices>
  <SalesInvoice>
    <LineItems>
      <LineItem>
        <ItemNumber>CR-10</ItemNumber>
        <ItemExternalId>1234</ItemExternalId>
        <Quantity>2</Quantity>
        <Ordered>2</Ordered>
        <BackOrdered>2</BackOrdered>
        <Unit>Each</Unit>
        <Description>Computer Repair - No Warranty</Description>
        <BasePrice>5</BasePrice>
        <DiscountPercentage>0</DiscountPercentage>
        <Price>5</Price>
        <Amount>10</Amount>
        <TaxCode>GP</TaxCode>
        <Account>42200</Account>
        <JobSites>
            <JobSite>
                <Site>Askew Shopping Centre</Site>
                <Percentage>50</Percentage>
            </JobSite>
            <JobSite>
                <Site>Basement Renovation</Site>
                <Amount>5</Amount>
            </JobSite>
        </JobSites>
      </LineItem>
    </LineItems>
  </SalesInvoice>
</SalesInvoices>

The following fields can be populated at the footer level of the sales invoice record.

Sage Field XML Field  Field Type  Input  Notes
Freight Freight/Amount double Optional
Freight Freight/TaxCode string(12)  Optional
Freight Freight/Tax1Amount  double  Optional
Freight Freight/Tax2Amount double Optional
Freight > Job Sites > Job Site Freight/JobSites/JobSite/Site double Optional 
Freight > Job Sites > Amount Freight/JobSites/JobSite/Amount double Optional 
Freight > Job Sites > Percentage JobSites/JobSite/Percentage double Optional 
Early Payment Terms > % Terms/DiscountPercentage double Optional
Early Payment Terms > Days  Terms/DiscountDays int Optional
Early Payment Terms > Net Days  Terms/NetDays  int  Optional
Message Message string(75) Optional  
<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices>
  <SalesInvoice>
    <Freight>
      <Amount>2.00</Amount>
      <TaxCode>GP</TaxCode>
      <Tax1Amount>0.10</Tax1Amount>
      <Tax2Amount>0.14</Tax2Amount>
      <JobSites>
        <JobSite>
            <Site>Askew Shopping Centre</Site>
            <Amount>1.12</Amount>
            <Percentage>50</Percentage>
        </JobSite>
      </JobSites>
    </Freight>
    <Terms>
      <DiscountPercentage>2</DiscountPercentage>
      <DiscountDays>30</DiscountDays>
      <NetDays>60</NetDays>
    </Terms>
    <Message>Thank you for your business!</Message>
  </SalesInvoice>
</SalesInvoices>