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 FROM OrderFlow (PULL)

Operations FROM OrderFlow (PUSH)

As described earlier in the PUSH operations described here are from the 'generic' OrderFlow integration. All of the messages are XML-based.

In order to assist with sequencing, the document (top level) element in the XML document contains a messageId attribute. The value for this attribute is a sequence number. For successive messages that refer to the same entity, this sequence number can be used to determine the order in which these messages were generated.

In some cases, the operation is triggered by an event on OrderFlow. In these cases, some extra information on the context of the operation is passed through by adding an event element wrapper around the detail of the message. The event element passes through information such as the name of the event, the user, time, etc.

The event element wrapper takes the following format:

<?xml version="1.0" encoding="UTF-8"?>
<event
  messageId="8"
  eventType="order_cancelled"
  userName="philz"
  eventTime="2015-01-21 10:29:51"
  entity="..."
  ... >
  <detail>
  ...
  </detail>
</event>

As with other push operations, the event element contains the ID for the OrderFlow message sent to the third party system.

We will see specific examples of messages that use the event wrapper in the sections below.

Product Operations

Inventory Push

The structure of the inventory push is the same as the inventory pull, it is used by OrderFlow to PUSH stock levels to Third Party applications when a change in stock levels triggers the event or as a scheduled background processes.

Operation Summary
Invocation Called from OrderFlow to client, periodic or event driven
Method HTTP POST
Example URL https://thirdpartyurl/productInventory.xml
Example input Body post as below

An example outgoing message is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<inventory messageId="15">
  <product
    inventoryId="453"
    sequenceId="453"
    externalReference="CD-SERGEANT"
    organisation="myco"
    site="global"
    total="186"
    allocated="0"
    available="186"
    frozen="0"
    onOrder="0"
    lastStockChangeId="86"
    lastLineRequirementChangeId="0" />
</inventory>

Note that each inventory push only includes products whose availability figure has modified since the last successful push operation. This is to allow for a more efficient inventory update notification process.

Note also that inventory notification is configured on a per organisation/channel basis. This configuration will include URLs, frequency, etc. The inventory notification can be periodic, or realtime. In the case of the latter, inventory notifications are triggered each time a change is made to the available quantity for a product.

The sequenceId value can be used to ensure that the latest inventory record is used for a product if multiple inventory messages are received out of sequence. For most products, the sequenceId will be the same as the inventoryId. However, if the product does not have an inventory record on the system, then the inventoryId will be zero, and the sequenceId will be set to the highest inventory ID value on the system at the time that the message was generated.

Stock Change Push

OrderFlow also supports a mechanism to notify third party systems of individual stock changes. This may be useful for third party systems that need an accurate audit of individual stock changes rather than simply the point in time inventory levels provided by the Product Inventory operation.

Examples of where an individual stock change feed may be required include:

  • a third party system needs to maintain a record of stock adjustments and writeoffs for auditing purposes.
  • OrderFlow needs to be integrated closely with another third party Warehouse Management System.

Stock Change Push notifications are tied to stock change events as they occur in OrderFlow, but can also be sent at regular intervals using a periodic report. A stock change event may generate one or more stock changes. For example, a move from one location to another will generate two stock changes: a move_out of one location, and a move_in to another.

Operation Summary
Invocation Called from OrderFlow to client on an event, or periodically
Method HTTP POST
Example URL https://thirdpartyurl/stockChanges.xml
Example input Body post as below

An example Stock Change Push entry is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<stockChanges
  messageId="14"
  organisation="myco"
  site="DEFAULT">
  <stockChange
    id="89"
    type="negative_adjustment"
    timestamp="2015-01-21 16:49:22"
    product="CD-SERGEANT"
    location="location_4"
    locationType="pickable"
    previousQuantity="187"
    changeQuantity="-1"
    newQuantity="186"
    user="philz">
    <note><![CDATA[Item dropped.]]></note>
  </stockChange>
</stockChanges>

For both the event and periodic report based approach, the system can be configured to only send particular types of stock changes. For example, internal stock moves within the system are generally interesting to a third party system. However, movements into locations for damaged items are more likely to be of interest.

A list of the most common types of stock changes is shown below:

Stock Change Types Summary
Delivery The receipt of an inbound item via an incoming Delivery to OrderFlow.
Move in The movement of an item into a location. Excludes damaged locations.
Move out The movement of an item out of a location. Excludes damaged locations.
Damaged in The movement of an item into a damaged location.
Damaged out The movement of an item out of a damaged location. Useful if item had been incorrectly recorded as damaged.
Negative adjustment Used if stock is not present in the current location as previously recorded.
Positive adjustment Used if the stock is present on a location where not previously recorded.
Pack debit debit Records a debit (reduction) in the stock holding of an item following the pack of a shipment.
Unpack credit If a shipment is unpacked, handles the credit of stock back onto the system.
Return Covers the receipt of incoming stock through the returns process.

Delivery and Purchase Order Operations

It is possible to configure OrderFlow to push back event notifications relating to incoming deliveries and purchase orders.

Each time a delivery line is recorded (when a given quantity of a particular product is added to the system), an event can be generated. Another point at which events can be triggered is when a delivery is completed by moving into the applied state. Finally, a purchase order (against which multiple deliveries can be recorded) can trigger an event notification when it is marked as completed; this will take place when no more deliveries are expected to be recorded against the purchase order.

One or more of these event types can be used by a third party application. Each of these is discussed in turn.

Delivery Line Push

The Delivery Line Push event is recorded when a new delivery line is added to the system.

Note that the event is generated only if a stock change is recorded against the delivery line; it is possible, for example, to record all the lines of the delivery and only apply the stock changes at the end in a single operation. In the latter case, no event will be generated at this stage.

Operation Summary
Invocation Called from OrderFlow to client on an event, or periodically
Method HTTP POST
Example URL https://thirdpartyurl/deliveryLine.xml
Example input Body post as below

An example delivery line is shown below. Note that as well as containing details on the product and quantity received, it includes the detail of the containing delivery. If the delivery was part of a purchase order, then details of the purchase order are included as well.

<?xml version="1.0" encoding="UTF-8"?>
<event
  messageId="4"
  eventType="delivery_line_applied"
  userName="philz"
  eventTime="2015-01-21 16:35:17"
  entity="rtd.domain.DeliveryLine">
  <detail>
    <deliveryLine
      id="24"
      product="ipod5"
      variation="standard"
      quantity="1"
      state="applied">
      <delivery
        id="33"
        type="from_licence_plates"
        state="receiving"
        site="SECOND"
        organisation="acme"
        supplierReference="default"
        supplierDeliveryReference="acmedel_1"
        deliveryDate="2013-07-18"
        created="2013-07-18 15:11:32">
        <purchaseOrder
          id="6"
          externalReference="po_acme_1"
          state="created"
          supplierPurchaseOrderReference="po_acme_1"
          manuallyCompleted="false"
          purchaseOrderDate="2013-09-05">
        </purchaseOrder>
      </delivery>
    </deliveryLine>
  </detail>
</event>

Note that as with the Order Event Push operations, the delivery uses the event element wrapper.

Delivery Push

At the point when a delivery is completed or applied, an event message can be triggered.

The Delivery Push message contains details on all of the delivery lines included within the delivery. This makes it possible to identify any delivery line messages that have not been received, or indeed, to rely on the Delivery Push message for a complete record of the deliveries applied.

Operation Summary
Invocation Called from OrderFlow to client on an event, or periodically
Method HTTP POST
Example URL https://thirdpartyurl/delivery.xml
Example input Body post as below

An example Delivery Push message is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<event
  messageId="6"
  eventType="delivery_applied"
  userName="philz"
  eventTime="2015-01-21 16:40:08"
  entity="rtd.domain.Delivery">
  <detail>
    <delivery
      id="33"
      type="from_licence_plates"
      state="applied"
      site="SECOND"
      organisation="acme"
      supplierReference="default"
      supplierDeliveryReference="acmedel_1"
      deliveryDate="2013-07-18"
      created="2013-07-18 15:11:32"
      completed="2015-01-21 16:40:08">
      <purchaseOrder
        id="6"
        externalReference="po_acme_1"
        state="partially_applied"
        supplierPurchaseOrderReference="po_acme_1"
        manuallyCompleted="false"
        purchaseOrderDate="2013-09-05">
      </purchaseOrder>
      <deliveryLines>
        <deliveryLine
          id="23"
          product="ipod5"
          variation="stock_only"
          quantity="1"
          state="applied" />
        <deliveryLine
          id="24"
          product="ipod5"
          variation="stock_only"
          quantity="1"
          state="applied" />
      </deliveryLines>
    </delivery>
  </detail>
</event>

The detail on the delivery includes a reference to the supplier, the supplier's reference for the delivery, as well as the date on which the delivery was expected, received and completed.

Purchase Order Push

A Purchase Order Push event can be triggered when a purchase order is completed on the system. When a delivery is completed on OrderFlow, the purchase order will automatically be completed if there are no further outstanding items on the purchase order. In this case, there is no need for a separate purchase order notification.

However, if the purchase does still contain outstanding items, it is possible to complete the purchase order manually if no further deliveries are expected against the purchase order, and in turn, generate a Purchase Order push notification.

Operation Summary
Invocation Called from OrderFlow to client on an event, or periodically
Method HTTP POST
Example URL https://thirdpartyurl/purchaseOrder.xml
Example input Body post as below

An example purchase order notification is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<event
  messageId="7"
  eventType="purchase_order_completed_manually"
  userName="philz"
  eventTime="2015-01-21 16:41:09"
  entity="rtd.domain.PurchaseOrder">
  <detail>
    <purchaseOrder
      messageId="7"
      id="6"
      externalReference="po_acme_1"
      state="completed"
      organisation="acme"
      site="SECOND"
      supplierReference="HAMA"
      supplierPurchaseOrderReference="po_acme_1"
      manuallyCompleted="true"
      purchaseOrderDate="2013-09-05">
      <note><![CDATA[No more items to receive.]]></note>
      <purchaseOrderLines>
        <purchaseOrderLine
          id="9"
          product="ipod5"
          quantity="10"
          outstanding="8"
          externalReference="acme1_1"
          state="created">
        </purchaseOrderLine>
        <purchaseOrderLine
          id="10"
          product="woodworm_zoom"
          quantity="8"
          outstanding="8"
          externalReference="acme1_2"
          state="created">
        </purchaseOrderLine>
        <purchaseOrderLine
          id="11"
          product="cyclepro_cape"
          quantity="20"
          outstanding="20"
          externalReference="acme1_3"
          state="created">
        </purchaseOrderLine>
      </purchaseOrderLines>
      <deliveries>
        <delivery
          id="33"
          type="from_licence_plates"
          state="applied"
          supplierDeliveryReference="acmedel_1"
          deliveryDate="2013-07-18"
          created="2013-07-18 15:11:32"
          completed="2015-01-21 16:40:08">
          <deliveryLines>
            <deliveryLine
              id="23"
              product="ipod5"
              variation="stock_only"
              quantity="1"
              state="applied" />
            <deliveryLine
              id="24"
              product="ipod5"
              variation="stock_only"
              quantity="1"
              state="applied" />
          </deliveryLines>
        </delivery>
      </deliveries>
    </purchaseOrder>
  </detail>
</event>

The Purchase Order Push notification contains details of all the lines in the purchase order, together with the quantity outstanding for each line.

In addition, the notification contains details on all of the deliveries applied against the purchase order, as well as lines contained within these deliveries. This makes it possible to verify that all of the deliveries expected against the purchase order have been received and processed.

Order Operations

Event Push

OrderFlow can be configured to push notification of changes made to an order to the associated third party applicaiton. The main changes of interest are usually changes to the status of an order or its associated shipments, for example, which take place for example when shipments are marked as packed or despatched.

Each of these different status types may also return additional information. Generic information, such as the time and user name of the event instigator, will always be available. In other cases, relevant additional information may be available.

Order events can be triggered at the order, shipment and/or line item level. The main ways in which a status notification will be triggered as as follows:

  • when a state change occurs, for example, when a shipment's status changes from picked to packed.
  • when a non-state changing operation is executed. For example, when a shipment is printed, no change of the shipment takes place.

However, it is still possible for a notification to be sent to the third party system.

Order Event Pushes can be triggered from events that take place on an order, the shipments used to despatch lines within the order, or on the lines themselves.

Exactly which combination of order, shipment and line item events and operations result in event notifications can be controlled through the OrderFlow configuration.

Operation Summary
Invocation Called from OrderFlow to client, typically event driven
Method HTTP POST
Example URL https://thirdpartyurl/orderEvent.xml

An example order state notification is shown below, in this case for the despatch of a shipment.

<?xml version="1.0" encoding="UTF-8"?>
<event
  messageId="4"
  eventType="shipment_despatched"
  userName="philz"
  eventTime="2015-01-22 11:34:08"
  entity="rtd.domain.Shipment"
  externalReference="141"
  operation="despatch"
  state="despatched">
  <detail>
    <order
      externalReference="141"
      state="despatched">
      <shipments>
        <shipment
          sequence="1"
          state="despatched"
          externalReference="1411"
          earliestShipDate="2009-12-07"
          courier="royalmail_dmo"
          despatchReference="12345678">
          <orderLines>
            <orderLine
              product="DVD-REDC"
              quantity="1"
              state="packed">
            </orderLine>
          </orderLines>
        </shipment>
      </shipments>
    </order>
  </detail>
</event>

An example for an order cancellation is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<event
  messageId="8"
  eventType="order_cancelled"
  userName="philz"
  eventTime="2015-01-21 10:29:51"
  entity="rtd.domain.OrderItem"
  externalReference="SPA_MULTI_4"
  state="cancelled"
  operation="cancel">
  <detail>
    <order
      externalReference="SPA_MULTI_4"
      state="cancelled">
      <shipments>
        <shipment
          sequence="1"
          state="cancelled"
          externalReference="SPA_MULTI_4"
          earliestShipDate="2014-11-05"
          courier="generic">
          <orderLines>
            <orderLine
              product="spa_sku2"
              quantity="3"
              state="cancelled">
            </orderLine>
            <orderLine
              product="spa_sku3"
              quantity="1"
              state="cancelled">
            </orderLine>
            <orderLine
              product="spa_sku4"
              quantity="2"
              state="cancelled">
            </orderLine>
          </orderLines>
        </shipment>
      </shipments>
    </order>
  </detail>
</event>

Note that in both cases, the operation has been triggered by event on the system. This is clear from the event element that wraps the detail of the message.

Shipment Operations

Payment Request

OrderFlow is able to send requests to third party applications to request that payment be taken for a shipment. This operation only applies for configurations for which up front payment does not occur, In these cases, payment is only taken when the lines for a particular shipment are verified to be in stock. The Payment Request operation is typically invoked within OrderFlow prior to picking to limit the operational consequences of a failed payment request.

Operation Summary
Invocation PUSH from OrderFlow to shopping cart at the point a shipment can be processed
Method HTTP POST
Example URL https://thirdpartyurl/requestPayment.xml

The data provided as part of the request includes the shipment and its containing order reference, as well as the line items associated with the payment request.

Example body text for the Payment Request invocation is shown below:

<paymentRequest date="2014-05-10 19:10:21">
  <order externalReference="multishipment">
    <shipments>
      <shipment externalReference="multishipment2">
        <orderLines>
          <orderLine product="DVD-BELOVED" quantity="3">
          </orderLine>
          <orderLine product="DVD-MATR" quantity="4">
          </orderLine>
        </orderLines>
      </shipment>
    </shipments>
  </order>
</paymentRequest>

Invocation of this operation by OrderFlow should trigger a corresponding Payment Response operation described below. However, these two operations are not tied to each other in a synchronous fashion.

Following receipt of the Payment Request, the third party application should return a success response to OrderFlow, at which point, OrderFlow will change the status of the relevant shipment to awating_payment_confirmation. Subsequently, the third party application will trigger payment to be taken via an interaction with the relevant payment gateway, after which the Payment Response will be used to communicate the result back to OrderFlow.

Payment Response

This service should be used by a third party applications to report the payment status of a shipment following earlier receipt of a Payment Request call from OrderFlow. The call to this method is invoked at some point after the third party application has had a chance to process the shipment referred to in the Payment Request call.

Operation Summary
Invocation Invoked by the 3rd party application responsible for interfaces with the payment gateway
Method HTTP POST
Example URL https://thirdpartyurl/shipmentresponse.xml

For successes it should simply replay the contents of the payment request, but indicate using a result attribute that the payment confirmation is successful.

For a success operation, the body of the Payment Response invocation would be as below.

<paymentResponse result="success">
  <order …>
    … contents as per Payment Request
  </order>
</paymentResponse>

Note the use of the success flag to indicate successful completion of the operation.

For failed payments, the body would be as shown below.

<paymentResponse result="failed">
  <message>Message from payment gateway</message>
  <code>XYZ</code>
  <order …>
    … contents as per Payment Request
  </order>
</paymentResponse>

Note that for both successful and failed payments the order line contents of the shipment is replayed back to OrderFlow. In the case of payment failure, a message and optional response code is passed back to OrderFlow. In this case, OrderFlow will set the state of the shipment to payment_request_failed. Only if payment is successful will the shipment be put back into the despatch workflow.

Return Operations

Return Push

A Return Push event can be triggered when a return is applied on the system.

Operation Summary
Invocation Called from OrderFlow to client on an event, or periodically
Method HTTP POST
Example URL https://thirdpartyurl/return.xml
Example input Body post as below

An example return notification is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<event
  messageId="243"
  eventType="return_item_applied"
  userName="philz"
  eventTime="2018-01-21 14:46:45"
  entity="rtd.domain.Return">
  <detail>
    <return 
      id="10035468782"
      authorised="true" 
      type="stock"
      site="DEFAULT"
      authorisation="10035468782"
      orderReference="10025908733"
    >
      <returnLine
        product="DVD-REDC"
        quantity="1" 
        reason="D - Wrong product sent" 
        condition="As new" 
        refund="true"/> 
      <returnLine
        product="DVD-BELOVED"
        quantity="2" 
        reason="E - Quality/Manufacturing fault" 
        condition="Product damaged (irreparable)" 
        refund="true"/> 
    </return>
  </detail>
</event>

The Return Push notification contains details of all the lines in the return.