Sage 50 US Purchase Invoice XML

The Import Purchase Invoices task allows you to create new purchase invoices, or update existing purchase 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 purchase 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 purchase invoice:-

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfPurchaseInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseInvoice Operation="Create">
    <ExternalId>99998</ExternalId>
    <VendorReference>ZYNK0001</VendorReference>
    <CustomerReference>HOLLAND<CustomerReference>
    <ShipToAddress>
      <Name>Zynk Software</Name>
      <Address>
        <Address1>123 Ice Valley</Address1>
        <Address2>Suite C</Address2>
        <City>New York City</City>
        <State>LA</State>
        <Zip>NY 10022</Zip>
        <Country>USA</Country>
      </Address>
    </ShipToAddress>
    <Date>2020-03-15T00:00:00</Date>
    <DateDue>2020-04-14T00:00:00</DateDue>
    <ReferenceNumber>99998</ReferenceNumber>
    <DropShip>false</DropShip>
    <WaitingForBill>false</WaitingForBill>
    <CustomerSalesOrderNumber>12345</CustomerSalesOrderNumber>
    <DiscountAmount>10.00</DiscountAmount>
    <DiscountDate>2020-03-25T00:00:00</DiscountDate>
    <TermsDescription>2% 10, Net 30 Days</TermsDescription>
    <ShipVia>None</ShipVia>
    <AccountReference>2000</AccountReference>
    <PurchaseInvoiceOrderLines PurchaseOrderKey='2ff80f5a-d4c2-4e9c-9151-4ca9e3fa87de' PurchaseOrderExternalId="235215" PurchaseOrderReferenceNumber="29471">
      <PurchaseInvoiceOrderLine>
        <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>
      </PurchaseInvoiceOrderLine>
    </PurchaseInvoiceOrderLines>
    <PurchaseInvoiceLines>
      <PurchaseInvoiceLine>
        <Quantity>4.00</Quantity>
        <InventoryItemReference>LAND-17100</InventoryItemReference>
        <Description>Weekly Landscaping Service</Description>
        <AccountReference>40000-LS</AccountReference>
        <UnitPrice>50</UnitPrice>
        <JobReference>BEATTY</JobReference>
      </PurchaseInvoiceLine>
    </PurchaseInvoiceLines>
    <VendorNote />
    <PrintVendorNoteAfterLineItems>false</PrintVendorNoteAfterLineItems>
    <InternalNote />
  </PurchaseInvoice>
</ArrayOfPurchaseInvoice>

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

In order to update an existing purchase invoice, you must provide at least one of the following fields in your XML to identify which purchase 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 purchase 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 purchase Invoices task.
<?xml version="1.0" encoding="utf-8"?>
<ArrayOfPurchaseInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseInvoice Operation="Update">
    <ExternalId>123</ExternalId>
    <ReferenceNumber>10322</ReferenceNumber>
    <Key>9683178a-43f4-4c47-b27f-e6e9f45dc8c3</Key>
  </PurchaseInvoice>
</ArrayOfPurchaseInvoice>

Main Purchase Invoice Fields

The below will let you specify the main fields required for a purchase invoice record.

Sage Field XML Field Example Field Type Field Length Input
N/A ExternalId 123 string 255 Optional
Vendor ID VendorReference ZYNK0001 string 20 Required, must exist in Sage as a vendor
Customer ID CustomerReference HOLLAND string 20 Optional, must exist in Sage as a customer
Name ShipToAddress/Name Zynk Software string 39 Optional
Address Line 1 ShipToAddress/Address1 123 Ice Valley string 30 Optional
Address Line 2 ShipToAddress/Address2 Suite C string 30 Optional
City ShipToAddress/City New York City string 20 Optional
St ShipToAddress/State LA string 2 Optional
Zip ShipToAddress/Zip NY 10022 string 12 Optional
Country ShipToAddress/Country USA string 15 Optional
Invoice Date Date 2020-03-15T00:00:00 datetime - Optional, defaults to day of import
Due Date* DateDue 2020-04-14T00:00:00 datetime - Optional
Invoice No ReferenceNumber 99998 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
Waiting on bill WaitingForBill false bool - Optional
Customer SO CustomerSalesOrderNumber 12345 string 20 Optional
Ship via* ShipVia None string 20 Optional
A/P account* AccountReference 2000 string 15 Optional
Vendor Note VendorNote Leave by the door string 2000 Optional
Print* PrintVendorNoteAfterLineItems false bool - 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
  • A/P account* - can only be what you have setup in Sage under Maintain Chart of Accounts.
  • 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"?>
<ArrayOfPurchaseInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseInvoice Operation="Create">
    <ExternalId>99998</ExternalId>
    <VendorReference>ZYNK0001</VendorReference>
    <CustomerReference>HOLLAND<CustomerReference>
    <ShipToAddress>
      <Name>Zynk Software</Name>
      <Address>
        <Address1>123 Ice Valley</Address1>
        <Address2>Suite C</Address2>
        <City>New York City</City>
        <State>LA</State>
        <Zip>NY 10022</Zip>
        <Country>USA</Country>
      </Address>
    </ShipToAddress>
    <Date>2020-03-15T00:00:00</Date>
    <DateDue>2020-04-14T00:00:00</DateDue>
    <ReferenceNumber>99998</ReferenceNumber>
    <DropShip>false</DropShip>
    <WaitingForBill>false</WaitingForBill>
    <CustomerSalesOrderNumber>12345</CustomerSalesOrderNumber>
    <ShipVia>None</ShipVia>
    <AccountReference>2000</AccountReference>
    <VendorNote>Leave by the door</VendorNote>
    <PrintVendorNoteAfterLineItems>false</PrintVendorNoteAfterLineItems>
    <InternalNote></Leave by the door>
  </PurchaseInvoice>
</ArrayOfPurchaseInvoice>

Terms Fields

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

Sage Field XML Field Example Field Type Field Length Input
Discount Amount DiscountAmount 10.00 decimal 15 Optional
Discount Date DiscountDate 2020-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"?>
<ArrayOfPurchaseInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseInvoice>
    <DiscountAmount>10.00</DiscountAmount>
    <DiscountDate>2020-03-25T00:00:00</DiscountDate>
    <TermsDescription>2% 10, Net 30 Days</TermsDescription>
  </PurchaseInvoice>
</ArrayOfPurchaseInvoice>

Apply To Purchase Order Line Fields

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

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

  • If one or more PurchaseInvoiceOrderLine elements are provided, any existing lines will be removed from the 'Apply To Purchase Order' tab in Sage. The lines you have provided in the XML will then be added to the 'Apply To Purchase Order' tab.
  • If no PurchaseInvoiceOrderLine 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
PO* @PurchaseOrderKey 2ff80f5a-d4c2-4e9c-9151-4ca9e3fa87de guid - Dependant
PO* @PurchaseOrderExternalId 235215 string 255 Dependant
PO* @PurchaseOrderReferenceNumber 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
  • PO* - At least one of the following attributes must be specified to identify which purchase order the lines relate to: PurchaseOrderKey, PurchaseOrderExternalId, PurchaseOrderReferenceNumber.
  • 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"?>
<ArrayOfPurchaseInvoice>
  <PurchaseInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <PurchaseInvoiceOrderLines PurchaseOrderKey='2ff80f5a-d4c2-4e9c-9151-4ca9e3fa87de' PurchaseOrderExternalId="235215" PurchaseOrderReferenceNumber="29471">
      <PurchaseInvoiceOrderLine>
        <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>
      </PurchaseInvoiceOrderLine>
    </PurchaseInvoiceOrderLines>
  </PurchaseInvoice>
</ArrayOfPurchaseInvoice>

Apply To Purchases Line Fields

The below will let you specify the 'apply to purchases' line item fields required for a purchase invoice. You can provide multiple PurchaseInvoiceLine elements as children of the PurchaseInvoiceLines element.

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

  • If one or more PurchaseInvoiceLine elements are provided, any existing lines will be removed from the 'Apply to Purchases' tab in Sage. The lines you have provided in the XML will then be added to the 'Apply to Purchases' tab.
  • If no PurchaseInvoiceLine 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 4 decimal - Optional
Item InventoryItemReference LAND-17100 string 20 Optional
Description Description Weekly Landscaping Service string 30 Optional
GL Account* AccountReference 40000-LS string 15 Optional
Unit Price UnitPrice 50 decimal - Optional, must be 0 if Quantity is 0
Job* JobReference BEATTY string 20 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"?>
<ArrayOfPurchaseInvoice>
  <PurchaseInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <PurchaseInvoiceLines>
      <PurchaseInvoiceLine>
        <Quantity>4.00</Quantity>
        <InventoryItemReference>LAND-17100</InventoryItemReference>
        <Description>Weekly Landscaping Service</Description>
        <AccountReference>40000-LS</AccountReference>
        <UnitPrice>50</UnitPrice>
        <JobReference>BEATTY</JobReference>
      </PurchaseInvoiceLine>
    </PurchaseInvoiceLines>
  </PurchaseInvoice>
</ArrayOfPurchaseInvoice>