Sage 200 Update Purchase Order XML

The Update Purchase Orders task allows you to update header analysis codes on existing orders and returns (purchase documents) in Sage 200, and progress purchase documents in Sage 200 through the ordering process (receiving, amending receipts, returning and amending returns). 

Tasks

XML

Sample XML snippets are provided throughout

Matching Purchase Orders/Returns

When updating purchase documents in Sage, you must provide one of the following key fields to identify the document to update.

XML Field Sage Field Example Field Type Field Length Input Notes
UniqueId POPOrderReturnID 236991 int - Required, unless using PurchaseOrderNumber, Id or SupplierOrderNumber The Sage 200 Purchase Order/Return database id (not visible in Sage UI).
PurchaseOrderNumber Order no/Return no 0000000024 string 20 Required, unless using UniqueId, Id or SupplierOrderNumber The Sage 200 document number.
Id - 123 string 4000 Required, unless using UniqueId, PurchaseOrderNumber or SupplierOrderNumber The Zynk Id of the Sage 200 document; assumes that the document was imported in the same Workflow that the Update Purchase Orders task is running from.
SupplierOrderNumber Supplier reference no 196 string 30 Required, unless using UniqueId, PurchaseOrderNumber or Id The Sage 200 supplier reference no; if more than one document exists with the same supplier reference no, the first match will be processed.

You should also specify the document type that you would like to update.

XML Field Sage Field Example Field Type Field Length Input Notes
PurchaseOrderType Type PopInvoice enum - Optional, assumed PopInvoice if not provided The Sage 200 Purchase Order/Return type. PopInvoice - Purchase Order PopReturn - Purchase Return 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <!-- Matching Purchase Order/Return by UniqueId-->
    <PurchaseOrder>
      <UniqueId>236991</UniqueId>
      <PurchaseOrderType>PopInvoice</PurchaseOrderType>
    </PurchaseOrder>

    <!-- Matching Purchase Order/Return by Id -->
    <PurchaseOrder>
      <Id>123</Id>
      <PurchaseOrderType>PopInvoice</PurchaseOrderType>
    </PurchaseOrder>

    <!-- Matching Purchase Order/Return by PurchaseOrderNumber -->
    <PurchaseOrder>
      <PurchaseOrderNumber>0000000024</PurchaseOrderNumber>
      <PurchaseOrderType>PopInvoice</PurchaseOrderType>
    </PurchaseOrder>

    <!-- Matching Purchase Order/Return by SupplierOrderNumber -->
    <PurchaseOrder>
      <SupplierOrderNumber>196</SupplierOrderNumber>
      <PurchaseOrderType>PopInvoice</PurchaseOrderType>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Delivery & Invoicing - Analysis codes

Analysis codes are imported from a collection, so you can import as many as are setup within Sage 200.  We lookup analysis codes by matching the Name from our XML to the Field Label in Sage.  The values that can be imported depend on how the analysis code is configured, if you need to import any value ensure Enter Free Text is enabled from Accounting System Manager -> Settings -> Maintain Analysis Codes.

XML Field Sage Field Example Field Type Field Length Input Notes
Name Analysis Code Customer Type string 60 Required The analysis code must already exist in Sage 200.
Value Value A string 60 Optional The value must already exist, unless Enter Free Text is enabled. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <AnalysisCodes>
        <AnalysisCode>
          <Name>Customer Type</Name>
          <Value>A</Value>
        </AnalysisCode>
        <AnalysisCode>
          <Name>Order Source</Name>
          <Value>Web</Value>
        </AnalysisCode>
      </AnalysisCodes>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Adjusting Purchase Order/Return Items

When adjusting purchase document item lines in Sage (receiving, amending receipts, returning, amending returns, updating analysis codes and updating delivery dates), you must provide one of the following fields to match the item line that you would like to process.

  • Every Purchase Order/Return is processed in it's entirety, meaning that if any of the Item adjustments cannot be fulfilled then all adjustments will be undone, you can think of each PurchaseOrder element provided in the data as representing a transaction against Sage, which will be rolled back if any of the item adjustments are unsuccessful. (Any rolled back operations will be captured against the Sage 200 Stock Item History)

If you want any valid Item adjustments to be processed regardless of whether or not other Item adjustments on the Order/Return are processed (atomically) then you should provide each Item adjustment in a separate PurchaseOrder element in the data. See examples at the bottom of this document.

XML Field Sage Field Example Field Type Field Length Input Notes
UniqueId POPOrderReturnLineID 233748 int - Required, unless using Sku The Sage 200 Purchase Order/Return line database id (not visible in Sage UI).
Sku Item TILE/WHT/20X20 string 30 Required, unless using UniqueId The Sage 200 item code.
PrintSequenceNumber - 2 int - Optional, if using Sku The position of the item on the Sage 200 document, could be used if adjusting a particular sku that appears more than once or for stricter validation. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <!-- Matching Purchase Order/Return Item by UniqueId -->
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <UniqueId>236991</UniqueId>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
    <!-- Matching Purchase Order/Return Item by Sku -->
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <Sku>TILE/WHT/20X20</Sku>
          <PrintSequenceNumber>2</PrintSequenceNumber>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Receiving Purchase Order Items

To receive a purchase order item, you must specify the amount to receive, and a reference number. You can optionally specify a date and narrative for the goods note.

N.B. It is not valid to provide a QtyToAmendReceive on the same XML Item that QtyToReceive has been provided on.

XML Field Sage Field Example Field Type Field Length Input Notes
GoodsNoteReference Reference 5230-H string - Required The reference/supplier GRN number.
GoodsNoteDate Date 2019-10-01 date - Optional The goods note date.
GoodsNoteNarrative Narrative Goods received string - Optional The goods note narrative.
@AllowOverReceipt - false bool - Optional Set to 'true' to allow the item to be over received in Sage.
QtyToReceive Qty Received 1 decimal - Required The quantity to receive. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <GoodsNoteReference>5230-H</GoodsNoteReference>
      <GoodsNoteDate>2019-10-01</GoodsNoteDate>
      <GoodsNoteNarrative>Goods received</GoodsNoteNarrative>
      <PurchaseItems>
        <Item AllowOverReceipt="false">
          <QtyToReceive>1</QtyToReceive>
        </Item>
      </PurchaseItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Amending Purchase Order Items Received

To amend the receipt of a purchase order item, you must specify the amount to amend the receipt by.

N.B. It is not valid to provide a QtyToReceive on the same XML Item that QtyToAmendReceive has been provided on.

XML Field Sage Field Example Field Type Field Length Input Notes
QtyToAmendReceive Qty Received 1 decimal - Required The quantity to reduce the receipt by. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <QtyToAmendReceive>2</QtyToAmendReceive>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Returning Purchase Order Items

To return a purchase order item, you must specify the amount to return.

N.B. It is not valid to provide a QtyToAmendReturn on the same XML Item that QtyToReturn has been provided on.

XML Field Sage Field Example Field Type Field Length Input Notes
QtyToReturn Qty Returned 1 decimal - Required The quantity to return. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseItems>
        <Item>
          <QtyToReturn>1</QtyToReturn>
        </Item>
      </PurchaseItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Amending Purchase Order Items Returned

To amend the returns of a purchase order item, you must specify the amount to amend the returns by.

N.B. It is not valid to provide a QtyToReturn on the same XML Item that QtyToAmendReturn has been provided on.

XML Field Sage Field Example Field Type Field Length Input Notes
QtyToAmendReturn Qty Returned 1 decimal - Required The quantity to reduce the returns by. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <QtyToAmendReturn>1</QtyToAmendReturn>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Adjusting Traceable Items

If you deal with traceable (batch or serial) items in Sage 200, then you can optionally provide the traceable identification numbers to receive/return the goods as.

Batch Items

If the item line being processed on the goods received note is configured in Sage 200 as a batch item, you can specify the batch information on the goods received note according to the below mapping.

XML Field Sage Field Example Field Type Field Length Input Notes
IdentificationNo Batch No 0000000001 string 30 Required The identifier of the traceable batch to process.
Quantity Qty Received/Qty To Return 2 decimal - Required The quantity of the traceable batch to use on the adjustment. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <Sku>TILE/WHT/20X20</Sku>
          <QtyToReceive>2</QtyToReceive>
          <Batches>
            <Batch>
              <IdentificationNo>0000000001</IdentificationNo>
              <Quantity>2</Quantity>
            </Batch>
          </Batches>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Serial Items

If the item line being processed on the goods received note is configured in Sage 200 as a serial item, you can specify the batch information on the goods received note according to the below mapping.

XML Field Sage Field Example Field Type Field Length Input Notes
IdentificationNo Batch No 0000000001 string 30 Required The identifier of the serial item to process.
Quantity Qty Received/Qty To Return 1 decimal - Required The quantity of a serial adjustment should always be 1. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <Sku>TILE/WHT/20X20</Sku>
          <QtyToReceive>2</QtyToReceive>
          <Batches>
            <Batch>
              <IdentificationNo>0000000001</IdentificationNo>
              <Quantity>2</Quantity>
            </Batch>
          </Batches>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Adjusting Purchase Order Item Analysis Codes

Analysis codes are imported from a collection, so you can import as many as are setup within Sage 200.  We lookup analysis codes by matching the Name from our XML to the Field Label in Sage.  The values that can be imported depend on how the analysis code is configured, if you need to import any value ensure Enter Free Text is enabled from Accounting System Manager -> Settings -> Maintain Analysis Codes.

XML Field Sage Field Example Field Type Field Length Input Notes
Name Analysis Code Customer Type string 60 Required The analysis code must already exist in Sage 200.
Value Value A string 60 Optional The value must already exist, unless Enter Free Text is enabled. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <AnalysisCodes>
            <AnalysisCode>
              <Name>Customer Type</Name>
              <Value>A</Value>
            </AnalysisCode>
            <AnalysisCode>
              <Name>Order Source</Name>
              <Value>Web</Value>
            </AnalysisCode>
          </AnalysisCodes>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Adjusting Purchase Order Item Delivery Dates

The delivery date for each purchase order item can either be specified as a single value that applies to the whole quantity, or as a series of dates along with the quantity expected to be received on that date. A single date should be specified via the RequestedDeliveryDate element, whereas multiple dates should be specified via the RequestedDeliveryDates element. If both are specified in the XML,RequestedDeliveryDates will take precedence.

When specifying multiple dates, you can choose which operation should be performed against sage:

  • Replace - Will remove all existing delivery dates from the item in Sage, and add the ones that are provided.
  • Update - Will update existing dates in Sage (matching based on the Position value), or add new ones. Any existing dates in Sage that aren't being updated will be preserved.

When specifying multiple dates, the total quantity across all dates must not exceed the quantity ordered of the item.

If the total quantity specified across all requested delivery dates is less than the quantity ordered of the item, the behaviour is determined by an optional attribute AllowQtyWithNoDeliveryDate, see the table below for more information on how this setting works.

XML Field Sage Field Example Field Type Field Length Input Notes
RequestedDeliveryDates/@Operation - Replace enum - Optional Valid values: Replace, Update. Defaults to Replace if not specified.
RequestedDeliveryDates/@AllowQtyWithNoDeliveryDate - true bool - Optional Valid values: true, false.
Defaults to true if not specified.
If true, the total quantity of all requested delivery dates can be less than the total quantity ordered, the remaining quantity will show in the Qty with no delivery date.
If false, the total quantity of all requested delivery dates must equal the quantity ordered, if it does not then the update will fail.
RequestedDeliveryDates/Position - 1 int - Optional Used with the Update operation to specify which date to update in Sage. If not specified, a new date will be added to Sage.
RequestedDeliveryDates/Date Delivery dates > Multiple Dates > Requested Date 2023-01-01 date - Dependant Required when a RequestedDeliveryDates collection is provided.
RequestedDeliveryDates/Quantity Delivery dates > Multiple Dates > Qty to Deliver 1 decimal - Dependant Required when a RequestedDeliveryDates collection is provided.
RequestedDeliveryDate Delivery dates - Requested 2023-01-01 date - Optional Will default to the RequestedDeliveryDate at the PurchaseOrder level if not provided. 
<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderItems>
        <Item>
          <RequestedDeliveryDates Operation="Update" AllowQtyWithNoDeliveryDate="true">
		    <RequestedDeliveryDate>
              <Position>1</Position>
		      <Date>2023-01-01</Date>
		      <Quantity>1</Quantity>
		    </RequestedDeliveryDate>
            <RequestedDeliveryDate>
              <Position>2</Position>
		      <Date>2023-01-02</Date>
		      <Quantity>1</Quantity>
		    </RequestedDeliveryDate>
          </RequestedDeliveryDates>
          <RequestedDeliveryDate>2023-01-01</RequestedDeliveryDate>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Complete Examples

Full samples of the XML are provided below.

Updating Purchase Order

<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderNumber>0000000024</PurchaseOrderNumber>
      <PurchaseOrderType>PopInvoice</PurchaseOrderType>
      <PurchaseOrderItems>
        <Item>
          <Sku>TILE/WHT/20X20</Sku>
          <QtyToReceive>2</QtyToReceive>
          <Batches>
            <Batch>
              <IdentificationNo>BAT0000001</IdentificationNo>
              <Quantity>2</Quantity>
            </Batch>
          </Batches>
        </Item>
        <Item>
          <Sku>TILE/BLK/20X20</Sku>
          <QtyToAmendReceive>2</QtyToAmendReceive>
          <Batches>
            <Batch>
              <IdentificationNo>SER0000001</IdentificationNo>
              <Quantity>1</Quantity>
            </Batch>
            <Batch>
              <IdentificationNo>SER0000002</IdentificationNo>
              <Quantity>1</Quantity>
            </Batch>
          </Batches>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Updating Purchase Return

<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderNumber>0000000025</PurchaseOrderNumber>
      <PurchaseOrderType>PopReturn</PurchaseOrderType>
      <PurchaseOrderItems>
        <Item>
          <Sku>TILE/WHT/20X20</Sku>
          <QtyToReturn>2</QtyToReturn>
          <Batches>
            <Batch>
              <IdentificationNo>BAT0000001</IdentificationNo>
              <Quantity>2</Quantity>
            </Batch>
          </Batches>
        </Item>
        <Item>
          <Sku>TILE/BLK/20X20</Sku>
          <QtyToAmendReturn>2</QtyToAmendReturn>
          <Batches>
            <Batch>
              <IdentificationNo>SER0000001</IdentificationNo>
              <Quantity>1</Quantity>
            </Batch>
            <Batch>
              <IdentificationNo>SER0000002</IdentificationNo>
              <Quantity>1</Quantity>
            </Batch>
          </Batches>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>

Updating Purchase Order Atomically

<?xml version="1.0" encoding="utf-8"?>
<Company
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PurchaseOrders>
    <PurchaseOrder>
      <PurchaseOrderNumber>0000000024</PurchaseOrderNumber>
      <PurchaseOrderType>PopInvoice</PurchaseOrderType>
      <PurchaseOrderItems>
        <Item>
          <Sku>TILE/WHT/20X20</Sku>
          <QtyToReceive>2</QtyToReceive>
          <Batches>
            <Batch>
              <IdentificationNo>BAT0000001</IdentificationNo>
              <Quantity>2</Quantity>
            </Batch>
          </Batches>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
    <PurchaseOrder>
      <PurchaseOrderNumber>0000000024</PurchaseOrderNumber>
      <PurchaseOrderType>PopInvoice</PurchaseOrderType>
        <Item>
          <Sku>TILE/BLK/20X20</Sku>
          <QtyToAmendReceive>2</QtyToAmendReceive>
          <Batches>
            <Batch>
              <IdentificationNo>SER0000001</IdentificationNo>
              <Quantity>1</Quantity>
            </Batch>
            <Batch>
              <IdentificationNo>SER0000002</IdentificationNo>
              <Quantity>1</Quantity>
            </Batch>
          </Batches>
        </Item>
      </PurchaseOrderItems>
    </PurchaseOrder>
  </PurchaseOrders>
</Company>