Skip to content

OrderFlow API Documentation

OrderFlow Ltd.

Document Version: 4.2.4

Document Built: 2024-02-16

This document and its content is copyright of OrderFlow Ltd. All rights reserved.
You may not, except with our express written permission, distribute, publish or commercially exploit the content.
Any reproduction of part or all of the contents in any form is prohibited.

Operations TO OrderFlow (PULL)

Operations TO OrderFlow (PULL)

Import Operations

Product Import

A mechanism for adding new products into the OrderFlow database, and for updating existing products (keyed on product code).

Products should first be defined within the third party application. The process that allows a user to create a new product should always associate it with a mandatory unique SKU (e.g. each size colour combination must have it's own SKU code).

"Bundles" of SKUs that might be represented in the third party system by a unique "Parent" SKU should not be passed to OrderFlow. The SKUs sent to OrderFlow should be the individual products rather than logical groupings of items which might be received and stored separately.

"Virtual" products that are not associated with physical items of stock in the warehouse should not be sent to OrderFlow.

When a new SKU is created within the third party system the SKU code, description and (optionally) any other relevant details should be passed to OrderFlow via the XML interface. The OrderFlow system should then create a new product code for the retailer (sales channel) and return an XML confirmation. The SKU code should be unique to the retailer, if the 'shared' flag is set as part of the product creation process the SKU code should be unique across the OrderFlow system.

Note that multi-line properties can be supported: simply use the string [BR] to represent line breaks.

Operation Summary
Invocation Called from client to OrderFlow as required
Method HTTP POST
URL /remotewarehouse/imports/importitems.xml
Header organisation

The value for the organisation HTTP header above will be the reference on OrderFlow for the organisation to which the product will belong. An example request body for the Product Import operation invocation is shown below.

<imports>
  <import type="product" operation="insert" externalReference="TEST_fullproduct">
    externalReference=TEST_fullproduct
    description=A description for the test product
    weight=100
    weightUnits=grams
    imageReference=TEST_fullproduct.gif
    type=default
    quantityOnOrder=10
    priceNet=10.50
    priceGross=11.50
    tax=1.50
    taxCode=T1
    currency=GBP
    currencyUnits=pounds
    costNet=10.50
    costGross=11.50
    costTax=1.50
    costTaxCode=T1
    costCurrency=GBP
    costCurrencyUnits=pounds
    userDefined1=User defined field value 1
    userDefined2=
    userDefined3=
    userDefined4=
    userDefined5=
    channel=MYCHANNEL
    type=default
    activated=true
  </import>
  <import type="product" operation="insert" externalReference="TEST_min_product">
    externalReference=TEST_min_product
    description=A description for the min product
    organisation=supershop
    type=default
    activated=true
  </import>
  <import type="product" operation="insert" externalReference="TEST_global_product">
    externalReference=TEST_global_product
    description=A description for the global product
    type=default
    activated=true
  </import>
</imports>

For a successful product import, OrderFlow will return output as shown below.

<importResult>
  <importSuccesses>
    <import type="product" operation="insert" externalReference="TEST_fullproduct"
      entity="rtd.domain.database.Product" item="rtd.domain.database.Product@172c384b"
      queryTime="2014-08-02 12:20:33.575" />
    <import type="product" operation="insert" externalReference="TEST_min_product"
      entity="rtd.domain.database.Product" item="rtd.domain.database.Product@c4983d8"
      queryTime="2014-08-02 12:20:33.596" />
    <import type="product" operation="insert" externalReference="TEST_global_product"
      entity="rtd.domain.database.Product" item="rtd.domain.database.Product@629bfaff"
      queryTime="2014-08-02 12:20:33.617" />
  </importSuccesses>
  <importFailures>
  </importFailures>
</importResult>

Note that failures are recorded per imported item. This happens when the data cannot be imported for some reason, for example if the imported item refers to data which is not present on the system.

The system also identifies and rejects duplicates when an attempt is made to reimport data which is already on the system. Similarly to failures, duplicates are also recorded separately using an importDuplicates element.

<importResult>
  <importSuccesses>
  </importSuccesses>
  <importFailures>
    <import type="product" operation="insert" externalReference="TEST_fullprosduct"
      queryTime="2014-08-02 12:31:35.582">
      <failureMessage>Unable to find
        any entity associated with identifier:
        ref:channel:missing_channel</failureMessage>
      <failureDetail>Unable to find any entity associated
        with identifier: ref:channel:missing_channel
        (rtd.exceptions.ImportMissingDataException)
        ...</failureDetail>
    </import>
  </importFailures>
  <importDuplicates>
    <import type="product" operation="insert" externalReference="TEST_min_product"
      queryTime="2014-08-02 12:31:35.717">
      <duplicateMessage>An instance
        of product with reference
        &apos;TEST_min_product&apos; is already present in
        the database.</duplicateMessage>
      <duplicateDetail>An
        instance of product with reference
        &apos;TEST_min_product&apos; is already present in
        the database.
        (rtd.exceptions.ValidationErrorException)
        ...</duplicateDetail>
    </import>
    <import type="product" operation="insert" externalReference="TEST_global_product"
      queryTime="2014-08-02
          12:31:35.784">
      <duplicateMessage>An instance
        of product with reference
        &apos;TEST_global_product&apos; is already present in
        the database.</duplicateMessage>
      <duplicateDetail>An
        instance of product with reference
        &apos;TEST_global_product&apos; is already present in
        the database.
        (rtd.exceptions.ValidationErrorException)
        ...</duplicateDetail>
    </import>
  </importDuplicates>
</importResult>

Note that temporary products can be imported directly using the Order Import operation. However, using this operation it is only possible to specify the product code (external reference) and the description.

See Product Import Fields for more details on fields which can be used for this operation.

Product Update

If a product description or other details are edited in the third party application, the new description or other values should be passed to OrderFlow using the Product Update operation.

The format of the message is the same as the product import but OrderFlow will apply a product update rather than an insert.

Operation Summary
Invocation Called from client to OrderFlow as required
Method HTTP POST
URL /remotewarehouse/imports/importitems.xml
Header organisation

The value for the organisation HTTP header will be the reference on OrderFlow for the organisation to which the product belongs.

The Product Update will make a request very similar to that of the Product Import, the key difference being the operation attribute.

<?xml version="1.0" encoding="UTF8"?>
<imports>
    <import type="product" operation="update" externalReference="TEST_fullproduct">
        externalReference=TEST_fullproduct
        description=An updated description for the test product
        weight=250
    </import>
</imports>

See Product Import Fields for more details on fields which can be used for this operation.

Order Import

The order import defines a mechanism for importing orders supplied as an XML document. The structure of the invocation is identical to the Product Import described earlier. All that differs is the URL used, and the contents of XML posted to the OrderFlow server.

Operation Summary
Invocation Called from client to OrderFlow as required
Method HTTP POST
URL /remoteorder/imports/importitems.xml
Header channel

The value for the channel HTTP header will be the reference on OrderFlow for the sales channel for the incoming order.

An example of a minimal Order Import input is shown below:

<?xml version="1.0" encoding="UTF8"?>
<imports>
  <import type="order" operation="insert" externalReference="TEST_order1">
    state=created
    validated=true
    paymentTransactionInfo=999
    customerComment=A comment from the customer
    totalPriceNet=10.0
    totalPriceGross=12.0
    totalTax=2.0
    totalTaxCode=T1
    shippingPriceNet=2.5
    shippingPriceGross=2.0
    shippingTax=2.0
    shippingTaxCode=T1
    currency=GBP
    currencyUnits=pounds
    placed=2014-08-31 07:16:02
    authorised=2014-08-31 08:16:10
    source=ebay
    channel=MYCHANNEL
    campaign=campaign_reference
    deliveryAddressLine1=Granvilla
    deliveryAddressLine2=Melton Hill
    deliveryAddressLine3=Woodbridge
    deliveryAddressLine4=Suffolk
    deliveryAddressLine5=
    deliveryAddressLine6=
    deliveryCountryCode=UK
    deliveryPostCode=IP12 1AX
    deliveryContactName=Phil Zoio
    deliveryEmailAddress=phil@orderflow-wms.co.uk
    deliveryDayPhoneNumber=01394 384181
    deliveryEveningPhoneNumber=01394 385000
    deliveryMobilePhoneNumber=07595 524200
    deliveryFaxNumber=01394 384181
    deliveryCompanyName=OrderFlow
    invoiceAddressLine1=OrderFlow
    invoiceAddressLine2=2 Manor Cottages
    invoiceAddressLine3=Swindon Road
    invoiceAddressLine4=Kington Langley
    invoiceAddressLine5=Chippenham
    invoiceAddressLine6=Wiltshire
    invoiceCountryCode=UK
    invoicePostCode=SN15 5ND
    invoiceContactName=Charlie Armor
    invoiceEmailAddress=charlie@orderflow-wms.co.uk
    invoiceDayPhoneNumber=01249 750564
    invoiceEveningPhoneNumber=01249 750564
    invoiceMobilePhoneNumber=
    invoiceFaxNumber=01249 750564
    invoiceCompanyName=OrderFlow
    userDefined1=ud1
    userDefined2=ud2
    userDefined3=ud3
    userDefined4=ud4
    userDefined5=ud5

    shipment.externalReference=TEST_myref_1
    shipment.state=ready
    shipment.earliestShipDate=1999-12-31
    shipment.deliveryInstruction=Please leave with neighbour if nobody at home
    shipment.despatchComment=
    shipment.despatchReference=
    shipment.weight=120
    shipment.weightUnits=grams
    shipment.itemCount=1
    shipment.addressLine1=
    shipment.addressLine2=
    shipment.addressLine3=
    shipment.addressLine4=
    shipment.addressLine5=
    shipment.addressLine6=
    shipment.countryCode=
    shipment.postCode=
    shipment.contactName=
    shipment.emailAddress=
    shipment.dayPhoneNumber=
    shipment.eveningPhoneNumber=
    shipment.mobilePhoneNumber=
    shipment.faxNumber=
    shipment.companyName=
    shipment.userDefined1=
    shipment.userDefined2=
    shipment.userDefined3=
    shipment.userDefined4=
    shipment.userDefined5=
    shipment.deliverySuggestionCode=express
    shipment.deliverySuggestionName=Express
    shipment.orderItem=entity:order

    orderLine.1.product.externalReference=DVD-BELOVED
    orderLine.1.quantity=10
    orderLine.1.state=created
    orderLine.1.totalPriceNet=4.0
    orderLine.1.totalPriceGross=5.0
    orderLine.1.totalTax=1.0
    orderLine.1.totalTaxCode=T1
    orderLine.1.unitPriceNet=
    orderLine.1.unitPriceGross=
    orderLine.1.unitTax=
    orderLine.1.unitTaxCode=
    orderLine.1.userDefined1=
    orderLine.1.userDefined2=
    orderLine.1.userDefined3=
    orderLine.1.userDefined4=
    orderLine.1.userDefined5=

    orderLine.2.product.externalReference=DVD-MATR
    orderLine.2.quantity=20
    orderLine.2.state=created
    orderLine.2.totalPriceNet=6.0
    orderLine.2.totalPriceGross=7.0
    orderLine.2.totalTax=1.0
    orderLine.2.totalTaxCode=T2
    orderLine.2.unitPriceNet=
    orderLine.2.unitPriceGross=
    orderLine.2.unitTax=
    orderLine.2.unitTaxCode=
    orderLine.2.userDefined1=
    orderLine.2.userDefined2=
    orderLine.2.userDefined3=
    orderLine.2.userDefined4=
    orderLine.2.userDefined5=

    orderLine.1.shipment=entity:shipment
    orderLine.2.shipment=entity:shipment

    orderAttribute.1.name=TEST_att1
    orderAttribute.1.title=Attribute 1
    orderAttribute.1.value=Attribute Value 1
    orderAttribute.1.orderItem=entity:order

    orderAttribute.2.name=TEST_att2
    orderAttribute.2.title=Attribute 2
    orderAttribute.2.value=Attribute Value 2
    orderAttribute.2.orderItem=entity:order
  </import>

  <import type="order" operation="insert" externalReference="TEST_minorder">
  #additional order properties as above
  ...
  </import>


  <import type="order" operation="insert" externalReference="TEST_with_product">
  #additional order properties as above
  ...
  </import>
</imports>

In general, the operation used for order imports will be insert. It is not possible to use the API to selectively update parts of an order (using the update operation). However, from OrderFlow 4.3.3 it is possible to use the reinsert to cancel (if necessary) an existing order and reinsert a new order with the same reference. Note that when this operation is used, if the order cannot be cancelled, then the import will be rejected and the order will be left unchanged.

Note also that campaign is an optional field (introduced in 3.8.0) which can be used to associate the incoming purchase order with an existing campaign.

See Order Import Fields for more details on fields which can be used for this operation.

Example Output: As with Product Import.

Referring to Products

Note that arbitrary order attributes can be imported using name value pairs as shown in the example above.

As the above example shows, there are two ways of referring to products. One is to refer to existing products within the system, using a line such as

orderLine.1.product.externalReference=DVD-BELOVED

The other is to import products as part of the order import, as shown in the snippet below.

product.1.externalReference=TEST_orderproduct1
product.1.description=A description for the new product 1
product.1.type=default
product.1.activated=true

orderLine.1.product=entity:product.1

Note that products need to be given a type attribute. For products which are only temporary, that is, for which no stock is to be checked into the warehouse, the type entry might be written as:

product.1.type=temporary

The range of properties available for the product entries is the same as is available for the standalone product import. However, the imported product must also have the product (and possibly numbered index) prefix, as the default imported entity in this case is order, not product.

line items are indexed, as shown for example in the expression

orderLine.1.quantity=10

Note that the referenced products, delivery codes, packing options, etc. need to be present and active in the database for the import to work successfully.

As with products, if multiple orders are imported, it is possible for some to import successfully and others to fail import. Again as with products, errors for particular items are specified using the importFailures element.

Note that multi-line properties can be supported: simply use the string [BR] to represent line breaks.

Merging orders with product definitions

It is possible to merge existing product definitions using the Order Import operation. This is useful in the case where the products may or may not be known about at the time of order import. In this case, the merge operation should be used for the order import, as shown below.

<?xml version="1.0" encoding="UTF8"?>
<imports>
  <import type="order" operation="merge" externalReference="TEST_myref">
    ...
    product.1.externalReference=TEST_orderproduct1
    product.1.description=A description for the new product 1
    product.1.type=temporary
    product.1.activated=true
    ...
  </import>
</imports>

In the example above, the product 'TEST_orderproduct1' may or may not be known to OrderFlow at the time of order import.

Note that orders and their associated order lines and shipments cannot be updated using the merge operation.

Supplier Purchase Order Import

The Supplier Purchase Order allows incoming deliveries to be associated with the purchase order that was used to order the incoming stock from a supplier. Multiple deliveries may be associated with one purchase order.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/imports/importitems.xml
Header organisation

The value for the organisation HTTP header will be the reference on OrderFlow for the organisation to which the purchase order applies.

OrderFlow can be configured to return details of incoming deliveries to the external system from which the associated supplier purchase order was received.

The following optional restrictions can be enforced by the OrderFlow configuration if appropriate:

  • Incoming deliveries that have been associated with a supplier purchase order can be restricted to the products contained in the order.
  • Incoming deliveries that have been associated with a supplier purchase order can be restricted to the product quantities contained in the order.
  • Supplier purchase orders associated with suppliers not already defined within OrderFlow can automatically create a new supplier definition.

Example input is shown below.

<?xml version="1.0" encoding="UTF8"?>
<imports>
  <import type="purchaseOrder" operation="insert"
    externalReference="TEST_po">
    purchaseOrder.supplierReference=TEST_purchaseOrder
    purchaseOrder.supplier=HAMA
    purchaseOrder.site=WAREHOUSE_1
    purchaseOrder.campaign=TEST_campaign_reference

    purchaseOrderLine.1.product=DVD-ABUG
    purchaseOrderLine.1.quantity=1
    purchaseOrderLine.1.purchaseOrder=purchaseOrder
    purchaseOrderLine.1.externalReference=poLine1

    purchaseOrderLine.2.product=DVD-FRAN
    purchaseOrderLine.2.quantity=1
    purchaseOrderLine.2.purchaseOrder=purchaseOrder
    purchaseOrderLine.2.externalReference=poLine2
  </import>
</imports>

Note that supplier purchase orders can also be imported as CSV documents through the CSV import interface. In this case, the document is not restricted to using the native format above.

Note that site is an optional field which is only applicable in multi-warehouse environments when the target site for the purchase order is known prior at the point of placing the purchase order. For single warehouse environments, the default site or warehouse will be used automatically.

Note that campaign is an optional field (introduced in 3.8.0) which can be used to associate the incoming purchase order with an existing campaign.

Advanced Shipping Note (ASN) Import

The Advanced Shipping Note (ASN) defines a mechanism by which incoming deliveries can be associated with existing orders. This provides the opportunity to avoid the overhead of checking stock into the warehouse, as items contained within an ASN delivery can be fed directly into order processing. Two types of ASNs are supported: Just-in-time ASNs, for which the individuals lines are associated with orders to be processed at the time of delivery, and Stock ASNs, for which the delivered items will be checked into the warehouse.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/imports/importitems.xml
Header organisation

The value for the organisation HTTP header will be the reference on OrderFlow for the organisation to which the ASN applies.

The format of the ASN import is very similar to that of the product and order import. The differences lie in the content of the data.

The example below is for a stock ASN, for which the associated delivery contents are expected to be placed in stock.

<?xml version="1.0" encoding="UTF8"?>
<imports>
  <import type="asn" operation="insert">
    asn.supplierReference=TEST_asn
    asn.supplier=abdc
    asn.site=WAREHOUSE_1
    asnLine.1.product=DVD-BELOVED
    asnLine.1.quantity=10
    asnLine.1.advancedShippingNote=asn
    asnLine.2.product=DVD-UNSG
    asnLine.2.quantity=20
    asnLine.2.advancedShippingNote=asn
  </import>
</imports>

The example below is for a Just-in-Time ASN, for which the associated delivery contents are expected to be associated with outstanding orders through a cross docking process.

<?xml version="1.0" encoding="UTF8"?>
<imports>
  <import type="asn" operation="insert">
    asn.supplierReference=TEST_asn
    asn.supplier=abdc
    asn.site=WAREHOUSE_1
    asnLine.1.product=DVD-BELOVED
    asnLine.1.quantity=10
    asnLine.1.advancedShippingNote=asn
    asnLine.1.orderItem=100
    asnLine.2.product=DVD-UNSG
    asnLine.2.quantity=20
    asnLine.2.advancedShippingNote=asn
    asnLine.2.orderItem=100
  </import>
</imports>

The third party system is responsible for providing the supplier reference for the ASN. The combination of supplier and supplier reference needs to be unique within OrderFlow. The supplier field itself is optional.

Note that the orderItem attribute used in the Just-in-Time ASN refers to the order which is identified using the externalReference attribute in the Order Import operation.

The following additional assumptions underlie the advance shipping note functionality. Some of these assumptions may be relaxed in future releases of OrderFlow:

  • At the time when the ASN is received by OrderFlow, all of the products associated with the ASN will already be known to OrderFlow. This may either be through a Product Import_, or implicitly via an Order Import.
  • If the ASN is for just-in-time orders, then all of the orders will be known to OrderFlow.
  • For a single ASN, all the lines will either be purely for just-in-time orders, or purely for stock check-in. In other words, the ASN will not contain a mixture of just-in-time and stock products.
  • For any order that the ASN covers, it should include in the same ASN the items required to satisfy all of the line items in that order. It should not, for example, be necessary to retrieve product items from stock to process an order contained within the ASN.
  • Orders referred to using ASNs cannot have multiple line items using the same SKU/product code.
  • The ASN is only supported for single shipment orders.
  • The ASN will be received electronically prior to the physical delivery of the items.

Note that the site is only required in multi-warehouse environments. For single warehouse environments, the default site or warehouse will be used automatically.

When receiving the ASN, OrderFlow will make sure the above conditions are satisfied, and in doing so will determine to which order lines each of the ASN line entries should be applied.

Note on the physical processing of the ASN

The note that follows is not part of the XML interface, but gives some background to how the contents of the ASN document will be used.

When the goods are received, the paperwork which accompanies the physical delivery should contain the ASN reference, as in the example below.

ASN: ASN_BARCODE
prod1 (The description for prod1) 
  Quantity: 10
prod2 (The description for prod2) 
  Quantity: 2
prod1 (The description for prod1) 
  Quantity: 4
prod3 (The description for prod3) 
  Quantity: 1

For each ASN line item, the product code will be inputted or scanned in for each item in the delivery. For just-in-time ASNs, when all of the lines associated with a particular order have been received, the user is directed to the packing screen for that order.

Returns Import

The Return Item import defines a mechanism for importing customer returns remotely, for example, via a Point of Sale (PoS) system. Multiple Return Lines may be associated with a Return Item.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/imports/importitems.xml
Header organisation

The value for the organisation HTTP header will be the reference on OrderFlow for the organisation to which the return applies.

The example below is for a Return Item with two Return Lines:

<?xml version="1.0" encoding="UTF8"?>
<imports>
<import type="return" operation="insert">
    return.orderReference=order_reference
    return.authorisation=TEST_return
    return.authorised=true
    return.type=goods_not_delivered
    return.storeId=001
    return.returnDate=2015-01-21 16:35:17
    return.user=philz
    return.organisation=myco
    return.site=WAREHOUSE_1
    return.note=Customer did not like colour
    #The line below is optional
    #return.channel=MYCHANNEL
    returnLine.1.quantity=1
    returnLine.1.reason=A - Not wanted
    returnLine.1.condition=As new
    returnLine.1.product=DVD-BELOVED
    returnLine.1.returnItem=return
    returnLine.2.quantity=1
    returnLine.2.reason= B - Not as described
    returnLine.2.condition=Packaging damaged
    returnLine.2.product=DVD-FRAN
    returnLine.2.returnItem=return
</import>
</imports>

Common elements such as product and channel follow the standard OrderFlow API conventions. Some additional detail on the XML Return Item and Line fields:

  • orderReference: The order number that this Return refers to.
  • authorisation: Either the authorisation reference or order number (depending on OrderFlow configuration). Must have a value if no orderReference is specified.

  • authorised: Whether the return is authorised.

  • type: The type of the return (e.g. 'goods_not_delivered', 'goods_damaged', 'unknown'). Note that this is configurable.

  • storeId: The ID of the store from which the return is being made.

  • note: Note to be added to return.

  • reason: Reason for the return, for example one of: [A - Not wanted, B - Not as described, C - Wrong size, D - Wrong product sent, E - Quality/Manufacturing fault, F - Damaged in transit, G - Late arrival, H - Other]. Note that this is configurable.

  • condition: Condition of the item(s) being returned, for example one of: [As new, Packaging damaged, Product damaged (refurbishable), Product damaged (irreparable)]. Note that this is configurable.

Note that the site is only required in multi-warehouse environments. For single warehouse environments, the default site or warehouse will be used automatically.

Campaign Import

The Campaign import defines a mechanism for importing campaigns remotely. Multiple Campaign Lines can be associated with a Campaign, and multiple Campaigns can be defined in a single import. Campaigns are only present in OrderFlow from version 3.7.9.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/imports/importitems.xml
Header channel

The value for the channel HTTP header will be the reference on OrderFlow for the sales channel to which the campaign will belong.

The example below is for a Campaign with two Campaign Lines:

<?xml version="1.0" encoding="UTF8"?>
<imports>
<import type="campaign" operation="insert" externalReference="campaign_reference">
    externalReference=campaign_reference
    name=campaign_name
    description=TEST campaign description
    channel=acmeweb
    startDate=2017-06-20
    breakDate=2017-06-24
    endDate=2017-06-25
    state=created
    campaignLine.1.quantity=5
    campaignLine.1.product.externalReference=ipod5
    campaignLine.1.campaign=entity:campaign
    campaignLine.2.quantity=2
    campaignLine.2.product.externalReference=star_wars_4
    campaignLine.2.campaign=entity:campaign
</import>
</imports>

Common elements such as product and channel follow the standard OrderFlow API conventions. Some additional detail on the XML Campaign fields:

  • startDate: The 'scheduled' start date of the campaign, when it effectively becomes active.
  • breakDate: The 'scheduled' date by which the primary activity on the campaign needs to be completed. SLAs can be measured against this date.

  • endDate: The date at which the campaign needs to be terminated.

Stock Move Task Import

The Stock Move Task import provides a mechanism for a third party system to initiate a sequence of stock moves within OrderFlow.

The stock moves may be for a variety of purposes. For example, they may involve the transfer of damaged stock from quarantine to outgoing locations prior to being returned to a supplier. In another example, the stock moves may entail the movement of items within an eCommerce warehouse to outgoing locations for subsequent shipment to stores.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/imports/importitems.xml
Header organisation

The value for the organisation HTTP header will be the reference on OrderFlow for the organisation to which the products reference in the task belong.

The example below shows a third party task import to return some damaged stock to a supplier.

<?xml version="1.0" encoding="UTF8"?>
<imports>
<import type="stockMoveTask" operation="insert">
externalReference=Widgets_RTN037625
taskDefinition=return_damaged_to_supplier
supplier=WidgetsRUs
site=Default
stockMoveLine.1.product=DVD-MATR
stockMoveLine.1.suggestedQuantity=1
stockMoveLine.1.thirdPartyReference=037625-01
stockMoveLine.1.stockMoveTask=stockMoveTask
stockMoveLine.2.product=DVD-ABUG
stockMoveLine.2.suggestedQuantity=2
stockMoveLine.2.thirdPartyReference=037625-02
stockMoveLine.2.stockMoveTask=stockMoveTask
</import>
</imports>

And this example shows a third party task import to transfer stock to a different warehouse.

<?xml version="1.0" encoding="UTF8"?>
<imports>
<import type="stockMoveTask" operation="insert">
externalReference=Calais_095441
taskDefinition=outgoing_stock_transfer
site=Default
targetSite=Calais
stockMoveLine.1.product=DVD-MATR
stockMoveLine.1.suggestedQuantity=1
stockMoveLine.1.thirdPartyReference=095441-01
stockMoveLine.1.stockMoveTask=stockMoveTask
stockMoveLine.2.product=DVD-ABUG
stockMoveLine.2.suggestedQuantity=2
stockMoveLine.2.thirdPartyReference=095441-01
stockMoveLine.2.stockMoveTask=stockMoveTask
</import>
</imports>

The following assumptions underlie the stock move task import functionality. Some of these assumptions may be relaxed in future releases of OrderFlow:

  • The third party system is responsible for providing its corresponding task reference (externalReference).
  • At the time when the task is received by OrderFlow, all of the products associated with the task will already be known to OrderFlow. This may be either through a Product Import_, or implicitly via an Order Import.

Note that the site is only required in multi-warehouse environments. For single warehouse environments, the default site or warehouse will be used automatically.

The taskDefinition determines how the system treats the lines once they have been imported. This is explained in a bit more detail in the next section.

Note on the processing of the imported task

The note that follows is not part of the XML interface, but gives some background to how the imported task will be actioned on OrderFlow.

When the task is imported, OrderFlow will create a stock move task of the relevant type, and capture the required lines (supplied in the XML) for that task. A background job will then run that will match the required lines for each imported task with the appropriate source (picking) and target (putaway) locations, thereby creating the source and target lines for the task.

Once the source and target lines have been identified, OrderFlow marks the stock move task as ready, allowing it to be processed in the same way as other stock move tasks on the system.

Imports using Custom Formats

The imports described above all assume that the native OrderFlow format is used. OrderFlow also support the import of data via other text based formats. For example, it is possible to support imports of data supplied as CSV files. Custom XML-based data formats can be accommodated using an XSLT transformation. Indeed, almost any text based format can be accommodated.

Operation Summary
Invocation Called from client to OrderFlow as required
Method HTTP POST
Example URL /remoteorder/imports/transformitems.xml
Parameters content: the content of the document being imported. handler:used to identify the transformation to be applied on the incoming data. operation:indicates the operation to be applied. Only required in situations where the operation is not already specified within the incoming document. If supplied, the value needs to be insert, update or merge.

Note that the 'magic' that takes place is in the setup of the handler, which needs to be correctly identified for the incoming data. Different handlers will be configured in different ways, depending on the format of the incoming data. For example, if the incoming format is CSV, the input handler may define mappings from the source fields generated by the third party system to the target fields understood by OrderFlow. The details of how the input handler is configured is outside of the scope of this document.

Note that the organisation scope of the operation above is determined using the organisation and/or channel header or parameters supplied as described in the Authentication section.

Product Operations

Inventory Pull

Third party applications can check the inventory level of a single product or set of products within OrderFlow. The SKU codes and "available stock" figures are returned. Depending on the filters used, this operation can return the inventory level for just a single product, a particular set of products or for all products in the inventory for a particular retailer.

Operation Summary
Invocation Called from client to OrderFlow as required
Method HTTP POST
Example URL /remotewarehouse/inventory.xml?channel=ch1&externalReferences=pr1,pr2,pr3
Parameters channel and/or organisation: retrieves all products for a particular channel and/or organisation combination, identified by reference (mandatory). site: if multi-site inventory is enabled, then identifies the site for which inventory is required (mandatory). externalReferences:product codes for which to retrieve inventories (optional). If no externalReferences are supplied the system will return all products associated with the channel, for which inventory exists. from: (optional) date or time from which to consider where a products inventory has changed (inclusive).

Note that in the use of the 'from' parameter, the date formats should be used as follows:

yyyy-MM-dd HH:mm:ss: use this to query within a specified time interval yyyy-MM-dd: use this to query within specified date interval

The Inventory Pull operation will result in OrderFlow returning output as shown below.

<inventory>
<product inventoryId="615" externalReference="DVD-BLDRNDC" site="global" 
         total="1" allocated="1" available="-1" frozen="0" .../>
<product inventoryId="616" externalReference="DVD-BLDRNDC" site="DEFAULT" 
         total="1" allocated="1" available="-1" frozen="0"/>
<product inventoryId="617" externalReference="DVD-BLDRNDC" site="SECOND" 
         total="0" allocated="0" available="0" frozen="0"/>
</inventory>

As indicated using ..., additional fields have been added to the inventory output. As with 4.0.3, these include:

<product ... inspection="0" damaged="0" quarantined="0" 
             onOrder="0" lastStockChangeId="0" lastLineRequirementChangeId="0"/>

The key figure is the available quantity, which will be zero or negative where a product is out of stock.

Note that the site parameter is only used in multi-site environments for which multi-site inventory is enabled. In these environments, optional values for site include:

  • global: returns the inventory values calculated across all sites on the system.
  • any: returns the inventory values for the 'global' site as well as for any other site for which the user has access permission.
  • by site reference, allows inventory values for a specific site to be retrieved.

Note that if multi-site inventory is supported, and no site parameter is supplied, then an inventory record calculated across all sites on the system is returned.

When using the 'from' parameter, a change is classed as an entry in the product_inventory table.

NOTE: If a products inventory is manually refreshed for any reason (and the underlying total, available, quarantined, onOrder etc are not updated), this would still trigger a new snapshot, and therefore be treated as an "update". Although this would be quite a rare occurrence, and would only add a few additional records into the endpoint.

Order Operations

The OrderFlow API can be used to create orders and optionally, to specify whether the line items within an order are spread across multiple shipments.

Orders can be cancelled through the API if the order state (out of stock, picked, etc.) is one that allows order cancellation. This business logic is configurable within OrderFlow.

Order Detail Pull

The OrderFlow API can be used to query the details on a particular order. This operation can be used to pick up all relevant information which pertains to a single order at a particular point in time, including the current order and associated shipment states, the availability of individual line items, the earliest ship date, the despatch reference, etc.

Operation Summary
Invocation Called from client to OrderFlow as required.
Method HTTP GET
URL /remoteorder/order/detail.xml?externalReference=81

The main order state values are the following:

Order State Description
created The order has been added to the system but not yet processed.
despatched All shipments within the order have been packed.
deleted an order is marked for deletion. Note that deleted orders are not accessible via the API.

Note that additional order states may be defined to support specific requirements within a particular instance of OrderFlow

Most of the order processing state tracking is done through shipments. Every order must contain at least one shipment, but it is also possible to support partial despatch of orders through multiple shipments. A selection of the applicable shipments states are shown below:

Shipment State Description
created The order and shipment have been added to the system but not yet processed.
ready The shipment is ready for processing, but processing of the shipment has not started. At this point, no stock will have been allocated to the shipment.
allocated Stock has been allocated for all of the order lines in the shipment. Note that if one or more of the order lines is out of stock, the shipment will remain in the 'ready' state.
on_hold The shipment has been placed on hold, because the earliest ship date is in the future.
picked All order lines for the shipment have been picked, but the shipment has not yet been packed.
packed The shipment has been packed but not yet despatched.
despatched The shipment has been despatched.
deleted The shipment has been marked for deletion. Note that deleted shipments are not accessible via the API.

In some circumstances it is necessary to track state changes at the order line level. Some of the states that apply for order lines:

Order Line State Description
created The order line has been added to the system but not yet processed.
allocated The stock required for the order line has been allocated.
picked The stock required for the order line has been picked.
out-of-stock The stock required for the order line is not available.
packed The order line has been packed.
deleted The order line has been marked for deletion. Note that deleted order lines are not accessible via the API.

Example output is show below.

<order externalReference="81" state="despatched">
 <shipments>
  <shipment sequence="1" state="created" earliestShipDate="2014-02-11">
   <orderLines>
    <orderLine product="steepletoneroxy1pink" quantity="1"
      state="created">
    </orderLine>
   </orderLines>
  </shipment>
 </shipments>
</order>

Order Cancellation

The process of deleting or cancelling an order is usually driven by the third party application in which the order was first generated. The process should attempt to delete the order within the OrderFlow system before changing the status of the order within the third party system.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remoteorder/order/cancel.xml
Parameters externalReference: the reference of the order to be cancelled. cancelChangesExternalReference: whether cancellation should change the order reference

The OrderFlow system may refuse to cancel an order if has been packed or despatched, in which case an error message will be returned and cancellation process should fail in the third party application.

Temporary vs Permanent Cancellation

One of the options on order cancellation is the use of the cancelChangesExternalReference. If set to false, the order reference will not be changed. Because OrderFlow does not allow duplicates of orders with the same reference it will not be possible to reimport the same order.

For some third party systems, a temporary cancellation of the order is required in order to support the reimport of a modified order. In this case, the old order needs to be cancelled in a way that will allow the same (but modified) order to be reimported into the system. In this case the cancelChangesExternalReference parameter is used with the value of true.

If not supplied, the implied value for the cancelChangesExternalReference is typically false, although this can be changed by configuration.

Error Cases

If an attempt is made to cancel an order, one of the following scenarios will apply:

  • the cancellation will take place as expected. All shipments in the order that have not already been completed will be cancelled.
  • the cancellation cannot take place because one of more of the shipments cannot be cancelled. For example, if a shipment has already been packed, it will need to be unpacked before it is eligible for cancellation.

The are situations when a cancellation cannot be attempted. If an attempt is made to cancel an order which is not on an authenticated channel, an UnauthorizedDataAccessException will be raised.

If the third party system attempts to cancel an order which has not yet been received by OrderFlow, then MissingDataException will be raised. The cancellation operation will return XML as in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
<message>
<![CDATA[Unable to find order for reference &apos;duff&apos;.]]>
</message>
<exception>rtd.exceptions.MissingDataException</exception>
<detail>
<![CDATA[... error detail below]]>
</detail>
</error>

When MissingDataException is raised, the most appropriate behaviour on the third party system is to allow the underlying cancellation to proceed, in contrast to other situations in which it would be more appropriate to block the cancellation.

Order Line Cancellation

As with orders, order line cancellation via the OrderFlow Remote API is typically initiated by the third party application from which the order line was received.

Once invoked, the process will attempt to delete the order line within OrderFlow. The shipment to which the order line belonged will be reset to the start of the despatch processing workflow. This is because paperwork, courier selections and other aspects of despatch processing will ususally need to change to reflect the modified shipment contents.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remoteorder/order/cancel.xml
Parameters orderReference: the reference of the order to be cancelled. productReference: the product reference (SKU) within the order line to be cancelled. thirdPartyReference: any (optional) third-party reference associated with the order line to be cancelled. This is used to identify the correct order line if there are multiple order lines for the same product.

Note that there must always be at least one order line present in an order (the last line can not be cancelled). If all of the order lines in an order need to be cancelled, then the Order Cancellation API operation should be used instead.

If an attempt is made to cancel an order line, one of the following outcomes will apply:

  • the cancellation will take place as expected. The order line will be removed from the order (and shipment).
  • the cancellation cannot take place. This may occur for a number of reasons, as described in the next section.
Error Cases

OrderFlow may reject an order line cancellation attempt if the line has already been packed or despatched.

Order line cancellation is currently not supported for orders which contain more than one order lines with the same product reference.

If an attempt is made to cancel an order line which is not on an authenticated channel, an UnauthorizedDataAccessException will be raised.

In both cases, an error message will be returned and the cancellation process should fail in the third party application.

If the third party system attempts to cancel an order line which has not yet been received by OrderFlow (or is simply not present), then a MissingDataException will be raised.

The cancellation operation in the event of an error will return XML as in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
<message>
<![CDATA[Unable to find order line with product &apos;duff&apos;.]]>
</message>
<exception>rtd.exceptions.MissingDataException</exception>
<detail>
<![CDATA[... error detail below]]>
</detail>
</error>

When a MissingDataException is raised, the most appropriate behaviour for the third party system is to allow the underlying cancellation to proceed. This differs from other cases where blocking the cancellation would be more appropriate.

Hold Order

(Available from release 4.3.1.2)

Third party applications may request that an order within the OrderFlow system be placed on-hold; if successful, all of the order's shipments will be moved to an on-hold state.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remoteorder/order/hold.xml
Header channel: required channel authentication value (see HTTP Authentication)
Parameters externalReference: the reference of the order to be placed on hold.

The OrderFlow system may refuse to place an order on-hold if it has been packed or despatched, in which case an error message will be returned and the process should consequently fail in the third party application.

Error Cases

If an attempt is made to place an order on-hold, one of the following scenarios will apply:

  • the action will take place as expected. All shipments in the order will be moved to an on-hold state.
  • the action cannot take place because one or more of the shipments cannot be placed on-hold. For example, if a shipment has already been packed.

There are situations when an on-hold request cannot be attempted. If an attempt is made to hold an order which is not on an authenticated channel, an UnauthorizedDataAccessException will be raised.

If the third party system attempts to hold an order which has not yet been received by OrderFlow, then a MissingDataException will be raised.

In an error scenario, the operation will return XML indicating the failure and reason, as in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
<message>
<![CDATA[Unable to find order for reference &apos;duff&apos;.]]>
</message>
<exception>rtd.exceptions.MissingDataException</exception>
<detail>
<![CDATA[... error detail below]]>
</detail>
</error>

Release Order

(Available from release 4.3.1.2)

Third party applications may request that an on-hold order within the OrderFlow system be released; if successful, all of the order's shipments will be moved back to their pre-held state.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remoteorder/order/release.xml
Header channel: required channel authentication value (see HTTP Authentication)
Parameters externalReference: the reference of the order to be released from on-hold.

The OrderFlow system will refuse to release an order if it's shipments are not in an-hold state, in which case an error message will be returned and the process should consequently fail in the third party application.

Error Cases

If an attempt is made to release an order from on-hold, one of the following scenarios will apply:

  • the action will take place as expected. All shipments in the order will be moved to their pre-held state.
  • the action cannot take place because one of more of the shipments cannot be released from on-hold. For example, if a shipment is not in an on-hold state.

There are situations when a release from on-hold request cannot be attempted. If an attempt is made to hold an order which is not on an authenticated channel, an UnauthorizedDataAccessException will be raised.

If the third party system attempts to hold an order which has not yet been received by OrderFlow, then a MissingDataException will be raised.

In an error scenario, the operation will return XML indicating the failure and reason, as in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
<message>
<![CDATA[Unable to find order for reference &apos;duff&apos;.]]>
</message>
<exception>rtd.exceptions.MissingDataException</exception>
<detail>
<![CDATA[... error detail below]]>
</detail>
</error>

Pending Shipments

This API call can be used to get a list of pending shipments for a particular sales channel.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP GET
URL /remoteorder/shipment/pending.xml
Parameters channel: the channel under consideration

For each shipment listed, the created date, shipment reference, order reference, state and earliest ship date is shown.

<?xml version="1.0" encoding="utf-8" ?>
<shipments>
  <shipment>
    <created>2014-01-18 00:00:00</created>
    <reference>1001</reference>
    <orderReference>100</orderReference>
    <state>out_of_stock</state>
    <earliestShipDate>2014-01-18</earliestShipDate>
  </shipment>
  <shipment>
    <created>2014-01-17 00:00:00</created>
    <reference>1011</reference>
    <orderReference>101</orderReference>
    <state>move_pending</state>
    <earliestShipDate>2014-01-17</earliestShipDate>
  </shipment>
  ...
  <shipment>
    <created>2014-01-27 00:00:00</created>
    <reference>OSC200612300011</reference>
    <orderReference>OSC20061230001</orderReference>
    <state>out_of_stock</state>
    <earliestShipDate>2014-01-28</earliestShipDate>
  </shipment>
  <shipment>
    <created>2014-01-28 00:00:00</created>
    <reference>OSC200703190011</reference>
    <orderReference>OSC20070319001</orderReference>
    <state>move_pending</state>
    <earliestShipDate>2014-01-28</earliestShipDate>
  </shipment>
</shipments>

Note that usage of this API may be throttled for performance reasons, as in some environments a large volume of data may be returned with each call. Clients are expected to use the operation sensibly.

Shipments State Change

(Available from release 4.3.2)

This API call can be used to get a list of shipments from Orderflow that have had a state change within a from/to date range for a particular sales channel and or organisation combination.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP GET
URL /remoteorder/shipment/statechange.xml
Parameters channel and/or organisation: retrieves all shipments for a particular channel and/or organisation combination, identified by reference (mandatory). from: the date or time from which to consider. to: (optional) the date or time to which to consider. includeLines: (optional) to include shipment lines in the shipment. site:

Note that in the use of the from and to parameter, the date formats should be used as follows:

yyyy-MM-dd HH:mm:ss: use this to query within a specified time interval yyyy-MM-dd: use this to query within specified date intervals

Note that the to parameter value is exclusive. In order to get shipments from March 27 2014, use 2014-03-27 to 2014-03-28. In order to get shipments from 3pm to 4pm on that day, you can use 2014-03-27 15:00:00 to 2014-03-27 16:00:00.

Note that the includeLines value can be either true or false, or omitted. If omitted, order lines will not be shown.

(Note that <originatingOrderReference> was introduced in 4.3.4)

For each shipment listed, the created date, shipment reference, order reference, state and earliest ship date is shown.

<?xml version="1.0" encoding="utf-8" ?>
<shipments>
  <shipment>
    <created>2014-01-18 00:00:00</created>
    <reference>1001</reference>
    <orderReference>100</orderReference>
    <originatingOrderReference>5049ecb6-6745-4c1e-8eed-be4c17204444</originatingOrderReference>
    <state>out_of_stock</state>
    <earliestShipDate>2014-01-18</earliestShipDate>
    <orderLines>
       <orderLine>
           <productReference>uom1</productReference>
           <quantity>4</quantity>
           <state>allocated</state>
           <thirdPartyReference></thirdPartyReference>
       </orderLine>
    </orderLines>
  </shipment>
  <shipment>
    <created>2014-01-17 00:00:00</created>
    <reference>1011</reference>
    <orderReference>101</orderReference>
    <originatingOrderReference>01ad2357-0e0e-46fe-9656-1605ffab7b2c</originatingOrderReference>
    <state>move_pending</state>
    <earliestShipDate>2014-01-17</earliestShipDate>
  </shipment>
  ...
  <shipment>
    <created>2014-01-27 00:00:00</created>
    <reference>OSC200612300011</reference>
    <orderReference>OSC20061230001</orderReference>
    <originatingOrderReference></originatingOrderReference>
    <state>out_of_stock</state>
    <earliestShipDate>2014-01-28</earliestShipDate>
  </shipment>
  <shipment>
    <created>2014-01-28 00:00:00</created>
    <reference>OSC200703190011</reference>
    <orderReference>OSC20070319001</orderReference>
    <originatingOrderReference></originatingOrderReference>
    <state>move_pending</state>
    <earliestShipDate>2014-01-28</earliestShipDate>
  </shipment>
</shipments>

Note that usage of this API may be throttled for performance reasons, as in some environments a large volume of data may be returned with each call. Clients are expected to use the operation sensibly.

The following two application properties, can be adjusted to restrict the number of rows retrieved

To restrict the maximum number of rows that can be returned remote.order.shipment.state.change.endpoint.max.row.returned

To restrict the number of days between from the supplied 'from' and 'to' date (if no 'to' date is used then today's date is applied remote.order.shipment.state.change.endpoint.max.days

Despatched Shipments Per Time Period

This operation allows third party systems to query despatched shipments over a specified time period.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remoteorder/shipment/despatches.xml
Parameters channel and/or organisation: (organisation available from 4.3.4) retrieves all despatched shipments for a particular channel and/or organisation combination, identified by reference (mandatory). from: the date or time from which to consider. to: the date or time to which to consider. includeOrderLines: (optional, from 3.7.8) to include order lines in the shipment. includePackageLines: (optional, from 4.0.5) to include lines for packages in the shipment

Note that in the use of the from and to parameter, the date formats should be used as follows:

yyyy-MM-dd HH:mm:ss: use this to query within a specified time interval yyyy-MM-dd: use this to query within specified date intervals

Note that the to parameter value is exclusive. In order to get shipments from March 27 2014, use 2014-03-27 to 2014-03-28. In order to get shipments from 3pm to 4pm on that day, you can use 2014-03-27 15:00:00 to 2014-03-27 16:00:00.

Note that the includeOrderLines value can be either true or false, or omitted. If omitted, order lines will not be shown.

(Note that <originatingOrderReference> was introduced in 4.3.4)

An example result set is shown below, which has been created with includeOrderLines set to true:

<?xml version="1.0" encoding="utf-8" ?>
<shipments>
    <shipment>
        <reference>831</reference>
        <orderReference>83</orderReference>
        <originatingOrderReference>5049ecb6-6745-4c1e-8eed-be4c17204444</originatingOrderReference>
        <state>despatched</state>
        <carrier>royalmail_tracked</carrier>
        <service>TPN01</service>
        <despatchReference>TT222211109GB</despatchReference>
        <completed>2014-04-25 09:30:08</completed>
        <orderLines>
            <orderLine>
                <productReference>spa_sku1</productReference>
                <quantity>5</quantity>
                <thirdPartyReference></thirdPartyReference>
            </orderLine>
            <orderLine>
                <productReference>spa_sku2</productReference>
                <quantity>3</quantity>
                <thirdPartyReference></thirdPartyReference>
            </orderLine>
        </orderLines>
    </shipment>
    <shipment>
        <reference>851</reference>
        <orderReference>85</orderReference>
        <originatingOrderReference>01ad2357-0e0e-46fe-9656-1605ffab7b2c</originatingOrderReference>
        <state>despatched</state>
        <carrier>royalmail_tracked</carrier>
        <service>TPN01</service>
        <despatchReference>TT222211090GB</despatchReference>
        <completed>2014-04-25 09:30:08</completed>
        <orderLines>
            <orderLine>
                <productReference>spa_sku1</productReference>
                <quantity>1</quantity>
                <thirdPartyReference></thirdPartyReference>
            </orderLine>
        </orderLines>
    </shipment>
    <shipment>
        <reference>1081</reference>
        <orderReference>108</orderReference>
        <originatingOrderReference></originatingOrderReference>
        <state>despatched</state>
        <carrier>royalmail_tracked</carrier>
        <service>TPS01</service>
        <despatchReference>TT222211069GB</despatchReference>
        <completed>2014-04-25 09:30:08</completed>
        <packages>
            <package despatchReference="TT222211069GB">
                <packageLines>
                    <packageLine 
                        product="spa_sku3"
                        quantity="10"
                        state="created">
                    </packageLine>
                </packageLines>
            </package>
            <package despatchReference="TT222211070GB">
                <packageLines>
                    <packageLine 
                        product="spa_sku3"
                        quantity="10"
                        state="created">
                    </packageLine>
                </packageLines>
            </package>
        </packages>
        <orderLines>
            <orderLine>
                <productReference>spa_sku3</productReference>
                <quantity>20</quantity>
                <thirdPartyReference></thirdPartyReference>
            </orderLine>
        </orderLines>
    </shipment>
</shipments>

Note that the returned data includes the carrier and service code, as well as the despatch reference, for each outgoing shipment.

For OrderFlow 4.0.5 and above, if multiple packages are present, then these will be displayed, together with the package references, as well as package lines, if the includePackageLines option is set.

Purchase Orders changed Within Time Period

(Available from release 4.3.2)

This operation allows third party systems to query purchase orders changed over a specified time period.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/purchaseorder/retrieve.xml
Parameters organisation: the organisation under consideration. from: the date or time from which to consider. to: (optional) the date or time to which to consider. includeLines: (optional) to include purchase order lines in the PO. site: (optional) the site under consideration. state: (optional) the returned purchase orders will be restricted by the state supplied

Note that in the use of the from and to parameter, the date formats should be used as follows:

yyyy-MM-dd HH:mm:ss: use this to query within a specified time interval yyyy-MM-dd: use this to query within specified date intervals

Note that the to parameter value is exclusive. In order to get deliveries from March 27 2014, use 2014-03-27 to 2014-03-28. In order to get po's from 3pm to 4pm on that day, you can use 2014-03-27 15:00:00 to 2014-03-27 16:00:00.

Note that the includeLines value can be either true or false, or omitted. If omitted, PO lines will not be shown.

An example result set is shown below, which has been created with includeLines set to true:

<?xml version="1.0" encoding="utf-8" ?>
<?xml version="1.0" encoding="utf-8" ?>
<purchaseOrders>
    <purchaseOrder>
        <id>9</id>
        <organisation>The Protein Works</organisation>
        <site>Aragon</site>
        <state>complete</state>
        <externalReference>TEST_po_2</externalReference>
        <thirdPartyReference></thirdPartyReference>
        <thirdPartyAdditionalReference></thirdPartyAdditionalReference>
        <note></note>
        <supplierReference>TEST_purchaseOrder_02</supplierReference>
        <type>supplier</type>
        <purchaseOrderDate></purchaseOrderDate>
        <created>2023-02-22 15:26:26</created>
        <requestedDeliveryDate></requestedDeliveryDate>
        <expectedDeliveryDate>2022-02-03 00:00:00</expectedDeliveryDate>
        <lastUpdated>2023-02-22 15:26:26</lastUpdated>
        <completed></completed>
        <purchaseOrderLines>
            <purchaseOrderLine>
                <productReference>weight_g01</productReference>
                <quantity>4100</quantity>
                <outstandingQuantity>4100</outstandingQuantity>
                <state>created</state>
                <externalReference>poLine1</externalReference>
                <thirdPartyReference></thirdPartyReference>
                <licencePlateReference></licencePlateReference>
                <operatorNote></operatorNote>
            </purchaseOrderLine>
            <purchaseOrderLine>
                <productReference>weight_g02</productReference>
                <quantity>5100</quantity>
                <outstandingQuantity>5100</outstandingQuantity>
                <state>created</state>
                <externalReference>poLine2</externalReference>
                <thirdPartyReference></thirdPartyReference>
                <licencePlateReference></licencePlateReference>
                <operatorNote></operatorNote>
            </purchaseOrderLine>

Applied Deliveries Per Time Period

(Available from release 4.3.0)

This operation allows third party systems to query applied deliveries over a specified time period.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/delivery/applied.xml
Parameters organisation: the organisation under consideration. from: the date or time from which to consider. to: (optional) the date or time to which to consider. includeLines: (optional) to include delivery lines in the delivery. site: (optional) the site under consideration. includePOData: (optional) to include the Purchase Order within the delivery node, and 'Purchase Order Line' thirdpartyReference within the delivery line nodes

Note that in the use of the from and to parameter, the date formats should be used as follows:

yyyy-MM-dd HH:mm:ss: use this to query within a specified time interval yyyy-MM-dd: use this to query within specified date intervals

Note that the to parameter value is exclusive. In order to get deliveries from March 27 2014, use 2014-03-27 to 2014-03-28. In order to get deliveries from 3pm to 4pm on that day, you can use 2014-03-27 15:00:00 to 2014-03-27 16:00:00.

Note that the includeLines value can be either true or false, or omitted. If omitted, delivery lines will not be shown.

An example result set is shown below, which has been created with includeLines set to true:

<?xml version="1.0" encoding="utf-8" ?>
<deliveries>
    <delivery>
        <id>4</id>
        <organisation>Myco Incorporated</organisation>
        <site>Default</site>
        <state>applied</state>
        <deliveryDate>2010-11-05 17:25:05</deliveryDate>
        <note></note>
        <supplierReference></supplierReference>
        <created>2010-11-05 17:25:05</created>
        <completed>2010-11-05 17:25:05</completed>
        <deliveryLines>
            <deliveryLine>
                <productReference>DVD-SPEED</productReference>
                <quantity>10</quantity>
            </deliveryLine>
            <deliveryLine>
                <productReference>DVD-FRAN</productReference>
                <quantity>5</quantity>
            </deliveryLine>
        </deliveryLines>
    </delivery>
    <delivery>
        <id>5</id>
        <organisation>Myco Incorporated</organisation>
        <site>Default</site>
        <state>applied</state>
        <deliveryDate>2010-11-05 17:25:56</deliveryDate>
        <note></note>
        <supplierReference></supplierReference>
        <created>2010-11-05 17:25:56</created>
        <completed>2010-11-05 17:25:56</completed>
        <deliveryLines>
            <deliveryLine>
                <productReference>DVD-FRAN</productReference>
                <quantity>5</quantity>
            </deliveryLine>
            <deliveryLine>
                <productReference>DVD-FDBL</productReference>
                <quantity>100</quantity>
            </deliveryLine>
        </deliveryLines>
    </delivery>
    <delivery>
        <id>6</id>
        <organisation>Myco Incorporated</organisation>
        <site>Default</site>
        <state>applied</state>
        <deliveryDate>2011-03-14 10:40:16</deliveryDate>
        <note></note>
        <supplierReference></supplierReference>
        <created>2011-03-14 10:40:16</created>
        <completed>2011-03-14 10:40:16</completed>
        <deliveryLines>
            <deliveryLine>
                <productReference>CD-UNFIRE</productReference>
                <quantity>100</quantity>
            </deliveryLine>
            <deliveryLine>
                <productReference>CD-SERGEANT</productReference>
                <quantity>200</quantity>
            </deliveryLine>
        </deliveryLines>
    </delivery>
</deliveries>

Applied Returns Per Time Period

(Available from release 4.3.0)

This operation allows third party systems to query applied returns over a specified time period.

Operation Summary
Invocation From 3rd party system to OrderFlow
Method HTTP POST
URL /remotewarehouse/returnitem/applied.xml
Parameters organisation: the organisation under consideration. from: the date or time from which to consider. to: (optional) the date or time to which to consider. includeLines: (optional) to include return lines in the return. site: (optional) the site under consideration. includeOriginatingOrderReference: (optional, available from 4.3.4) to include the originating order reference in the returned data.

Note that in the use of the from and to parameter, the date formats should be used as follows:

yyyy-MM-dd HH:mm:ss: use this to query within a specified time interval yyyy-MM-dd: use this to query within specified date intervals

Note that the to parameter value is exclusive. In order to get returns from March 27 2014, use 2014-03-27 to 2014-03-28. In order to get returnds from 3pm to 4pm on that day, you can use 2014-03-27 15:00:00 to 2014-03-27 16:00:00.

Note that the includeLines value can be either true or false, or omitted. If omitted, return lines will not be shown.

Note that the includeOriginatingOrderReference value can be either true or false, or omitted. If omitted, the originating order reference will not be included.

An example result set is shown below, which has been created with includeLines and includeOriginatingOrderReference both set to true:

<?xml version="1.0" encoding="utf-8" ?>
<returns>
    <return>
        <id>1</id>
        <organisation>Myco Incorporated</organisation>
        <site>Default</site>
        <state>applied</state>
        <returnDate>2011-07-29 14:18:02</returnDate>
        <note></note>
        <type>goods_not_delivered</type>
        <orderReference></orderReference>
        <originatingOrderReference>5049ecb6-6745-4c1e-8eed-be4c17204444</originatingOrderReference>
        <created>2011-07-29 14:04:32</created>
        <completed>2011-10-14 14:50:47</completed>
        <returnLines>
            <returnLine>
                <productReference>PHO-IPHONE4</productReference>
                <quantity>4</quantity>
                <state>applied</state>
                <returnCondition></returnCondition>
                <reason></reason>
                <note>No reason given</note>
            </returnLine>
            <returnLine>
                <productReference>PHO-HTC-SENSATION</productReference>
                <quantity>2</quantity>
                <state>applied</state>
                <returnCondition></returnCondition>
                <reason></reason>
                <note></note>
            </returnLine>
        </returnLines>
    </return>
    <return>
        <id>26</id>
        <organisation>Myco Incorporated</organisation>
        <site>Default</site>
        <state>applied</state>
        <returnDate>2012-01-24 00:00:00</returnDate>
        <note>adfa</note>
        <type>goods_not_delivered</type>
        <orderReference></orderReference>
        <originatingOrderReference>01ad2357-0e0e-46fe-9656-1605ffab7b2c</originatingOrderReference>
        <created>2019-12-02 16:04:38</created>
        <completed>2019-12-03 16:34:21</completed>
        <returnLines>
            <returnLine>
                <productReference>DVD-FRAN</productReference>
                <quantity>10</quantity>
                <state>applied</state>
                <returnCondition></returnCondition>
                <reason>B - Not as described</reason>
                <note></note>
            </returnLine>
        </returnLines>
    </return>
</returns>