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

Updating Purchase Orders in Sage 200

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>