Sales Orders


addOrders

The addOrders method allows the developer to add new orders to the Volo platform.

Request

Parameters Description Values Required/Optional
Order To define order line values String Required
Payment To define payment details String Optional
Currency Code To define Currency of the order ISO Currency Code Optional - default to GBP
OrderItems To define items on order String Required

Example Request

<arg0>
    <Order>
            <OrderType>Order</OrderType>    
            <OrderSource>Manual</OrderSource>
            <ExternalReference>5434</ExternalReference>
            <Date>01/01/2015</Date>
            <CustomerCompany>Volo Commerce</CustomerCompany>
            <CustomerName>Example Customer</CustomerName>
            <CustomerAddress1>4th Floor, St James House</CustomerAddress1>
            <CustomerAddress2>St James Square</CustomerAddress2>
            <CustomerCity>Cheltenham<CustomerCity>
            <CustomerCounty>Gloucestershire</CustomerCounty>
            <CustomerPostcode>GL503PR</CustomerPostcode>
            <CustomerCountry>GB</CustomerCountry>
            <CustomerEmail>example@volocommerce.com<CustomerEmail>
            <CustomerTelephone>+44 (0)1242 509889</CustomerTelephone>
            <DeliveryCompany>Volo Commerce</DeliveryCompany>
            <DeliveryName>Example Customer</DeliveryName>
            <DeliveryAddress1>4th Floor, St James House</DeliveryAddress1>
            <DeliveryAddress2>St James Square</DeliveryAddress2>
            <DeliveryCity>Cheltenham</DeliveryCity>
            <DeliveryCounty>Gloucestershire</DeliveryCounty>
            <DeliveryPostcode>GL503PR</DeliveryPostcode>
            <DeliveryCountry>GB</DeliveryCountry>
            <ShippingCost>9.95</ShippingCost>
            <OrderTotal>35.00</OrderTotal>
            <PaymentComplete>Y</PaymentComplete>
        <Payments>
            <Payment>
                <PaymentMethod>External</PaymentMethod>
                <Amount>35.00</Amount>
                <PaymentReference>PAYM456</PaymentReference>
            </Payment>
        </Payments>
            <CurrencyCode>GBP</CurrencyCode>
        <OrderItems>
            <Item>
                <StockNumber>ABC123</StockNumber>
                <ProductTitle><![CDATA[Volo Executive Pen]]></ProductTitle>
                <Quantity>1</Quantity>
                <UnitCost>25.05</UnitCost>
            </Item>
        </OrderItems>
    </Order>
</arg0>
    

Example Response

<Return>
    <collectOrderResponse>
    <externalReference>{} </externalReference>
    <externalSourceID> </externalSourceID>
    <orderID> </orderID>
    <orderStatus> </orderStatus>
    <refundOrderStatus>{optional} </refundOrderStatus>
    <sellerUserName> </sellerUserName>
    </collectOrderResponse>
</Return>
    


addOrderHistories

Request

Parameters Description Values Required/Optional
ESPOrderNumber To define specific orders to be returned Int Optional
HistoryEntry Description = description of event | Type = Only "NOTE" is allowed | UserName = the user that actioned the event | TimeStamp = Not used, will always be set to current time string Required

Example Request

<arg0>
   <OrderHistory>
      <ESPOrderNumber>5439</ESPOrderNumber>
      <HistoryEntry Description="Packed waiting shipment" Type="NOTE" UserName="Warehouse1" />
   </OrderHistory>
</arg0>

Example Response

<return>
   <responseMessage>1 Orders Updated  successfully</responseMessage>
   <responseStatus>OK</responseStatus>
   <timestamp>2015-07-07T09:31:30.156+01:00</timestamp>
</return>


getOrderHistories

The getOrderHistories method allows the developer to notes/audit descriptions on specific orders.

Request

Parameters Description Values Required/Optional
ESPOrderNumber The Volo order number to be returned. Int Optional
HistoryEntry Not used string Not Used

Example Request

<arg0>
   <OrderHistory>
      <ESPOrderNumber>5439</ESPOrderNumber>
   </OrderHistory>
</arg0>

Response

Name Description Type
ESPOrderNumber The Volo order number. Int
HistoryEntry Description = description of event | Type = event type | UserName = the user that actioned the event | TimeStamp = Time and date at which the event took place string

Example Response

<return>
   <responseStatus>OK</responseStatus>
   <timestamp>2015-07-07T09:00:41.985+01:00</timestamp>
   <OrderHistories>
      <OrderHistory>
         <ESPOrderNumber>5439</ESPOrderNumber>
         <HistoryEntry Description="this is a test" Type="NOTE" UserName="support.sw" TimeStamp="2015-06-29T15:16:20+01:00" />
         <HistoryEntry Description="Email Request Added: WebsiteOrderReceived" Type="EMAIL" TimeStamp="2015-06-26T12:57:04+01:00" />
         <HistoryEntry Description="Invoice Number Allocated: 41444" Type="NOTE" TimeStamp="2015-06-26T12:57:04+01:00" />
         <HistoryEntry Description="Order Received from WWW" Type="ORDER_IN" UserName="" TimeStamp="2015-06-26T12:57:04+01:00" />
      </OrderHistory>
   </OrderHistories>
</return>


getOrders

The getOrders method allows the developer to request orders from within the Volo platform.

Request

Parameters Description Values Required/Optional
CostPrice Operator = EQUALS, NOT_EQUALS, LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN_OR_EQUALS | Value = {cost price value} Int Optional
customerEmail To define orders returned by a specific customer email address String Optional
customerId To define orders returned by a specific customer ID Int Optional
endDate To define orders returned in a specific date range DateTime Optional
newOrdersOnly Return new orders only. 1 = new orders only | 0 = all orders Boolean Optional
OrderSource Returns order from specific marketplaces only String Optional
OrderTotal Operator = EQUALS, NOT_EQUALS, LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN_OR_EQUALS | Value = {order total value} Int Optional
paidOnly To return orders that are in balance. 1 = paid | 0 = all orders Boolean Optional
ShippingCost Operator = EQUALS, NOT_EQUALS, LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN_OR_EQUALS | Value = {shipping cost value} Boolean Optional
startDate To define orders returned in a specific date range DateTime Optional

Example Request

<arg0>
   <endDate>2015-07-03+01:00</endDate>
   <newOrdersOnly>false</newOrdersOnly>
   <orderSource>WWW</orderSource>
   <OrderTotal>
      <Operator>LESS_THAN</Operator>
      <Value>150.99</Value>
   </OrderTotal>
   <startDate>2015-06-03+01:00</startDate>
</arg0>

Response

Name Description Type
OrderType Fixed to 'Order'. string
ESPOrderNo The returned Volo order number(s) Int
InvoiceNumber The returned Volo invoice number(s) Int
ExternalReference The maketplace order number. string
Date The date that the order was placed returned as an Epoch value (ms since 01/01/1970 00:00:00) Int
CustomerCompany The buyers billing company name varchar
CustomerName The buyers billing full customer name varchar
CustomerAddress1 The buyers billing address line 1 varchar
CustomerAddress2 The buyers billing address line 2 varchar
CustomerCity The buyers billing city varchar
CustomerCounty The buyers billing county/state varchar
CustomerPostcode The buyers billing postcode/zipcode varchar
CustomerCountry The buyers billing country varchar
CustomerEmail The buyers email address varchar
CustomerNotes The buyer instructions/notes as populated at the marketplace checkout. varchar
DeliveryCompany The recipient's shipping company name varchar
DeliveryName The recipient's shipping full name varchar
DeliveryAddress1 The recipient's shipping address line 1 varchar
DeliveryAddress2 The recipient's shipping address line 2 varchar
DeliveryCity The recipient's shipping city varchar
DeliveryCounty The recipient's shipping county/state varchar
DeliveryPostcode The recipient's shipping postcode/zipcode varchar
DeliveryCountry The recipient's shipping country varchar
DeliveryTelephone The delivery phone number varchar
ShippingCost The total shipping amounr double
Insurance The total insurance amount paid by the customer double
Discount he total discount amount applied to the whole order double
OrderTotal The total order value double
PaymentComplete A true or false value to indicate whether the payment amount balances to the order total. String
Payments PaymentMethod, PaymentReference, PayPalProtectionEligibility - contained within the nested 'Payment' group varchar
CurrencyCode The ISO currency code e.g. GBP varchar
SellerUsername The seller account name where the order was placed varchar
CourierProfileName The name given to the courier profile associated with the order. The courier profile contains data on courier, service, weight, package type, etc. and is usually assigned to orders based on the 'Courier Rules' matrix table VarChar
WebProductID The website item referemce varchar
StockNumber The Volo stock number contained in the order varchar
ItemNumber The marketplace item reference int
ProductTitle The title of the product as populated on the given marketplace varchar
Quantity The quantity or items ordered int
UnitCost The price of the item as paid for by the buyer double
TaxRate The tax percentage amount as applied to the item e.g. 20 Int
UnitCostIncludesTax Y or N. Whether the UnitCost of the item value includes or excludes tax Boolean
Weight THe weight of the ordered item in grams int
BuyerId The buyer's marketplce account name varchar

Example Response

<return>
   <responseStatus>OK</responseStatus>
   <timestamp>2015-07-07T09:23:18.078+01:00</timestamp>
   <OutgoingOrders>
      <Order>
         <OrderType>Order</OrderType>
         <ESPOrderNo>5434</ESPOrderNo>
         <InvoiceNumber>41441</InvoiceNumber>
         <ExternalReference>j100000178</ExternalReference>
         <Date>2015-06-08+01:00</Date>
         <CustomerCompany />
         <CustomerName>Example Customer</CustomerName>
         <CustomerAddress1>St. Jame's House</CustomerAddress1>
         <CustomerAddress2 />
         <CustomerCity>CHELTENHAM</CustomerCity>
         <CustomerCounty />
         <CustomerPostcode>GL51</CustomerPostcode>
         <CustomerCountry>GB</CustomerCountry>
         <CustomerEmail>example@volocommerce.com</CustomerEmail>
         <CustomerNotes>0</CustomerNotes>
         <DeliveryCompany />
         <DeliveryName>Example Customer</DeliveryName>
         <DeliveryAddress1>St. Jame's House</DeliveryAddress1>
         <DeliveryAddress2 />
         <DeliveryCity>CHELTENHAM</DeliveryCity>
         <DeliveryCounty />
         <DeliveryPostcode>GL51</DeliveryPostcode>
         <DeliveryCountry>GB</DeliveryCountry>
         <DeliveryTelephone>01242 6669996</DeliveryTelephone>
         <ShippingMethod>flatrate_flatrate</ShippingMethod>
         <ShippingCost>2.91</ShippingCost>
         <Insurance>0</Insurance>
         <Discount>0</Discount>
         <OrderTotal>30.51</OrderTotal>
         <PaymentComplete>false</PaymentComplete>
         <Payments>
            <Payment>
               <PaymentMethod>Credit Card</PaymentMethod>
               <PaymentReference>checkmo</PaymentReference>
               <PayPalProtectionEligibility>false</PayPalProtectionEligibility>
            </Payment>
         </Payments>
         <CurrencyCode>GBP</CurrencyCode>
         <SellerUsername>Magento</SellerUsername>
         <OrderItems>
            <Item>
               <WebProductID>15800</WebProductID>
               <StockNumber>mag02-single-test</StockNumber>
               <ItemNumber>235</ItemNumber>
               <ProductTitle>Royal Mint 25th Anniversary &#163;1 Coin Collections Set</ProductTitle>
               <Quantity>1</Quantity>
               <UnitCost>27.60</UnitCost>
               <TaxRate>0</TaxRate>
               <UnitCostIncludesTax>Y</UnitCostIncludesTax>
               <Weight>0</Weight>
            </Item>
         </OrderItems>
         <BuyerId />
      </Order>
   </OutgoingOrders>
   <PaginationResult>
      <TotalNumberOfEntries>10</TotalNumberOfEntries>
      <TotalNumberOfPages>1</TotalNumberOfPages>
   </PaginationResult>
</return>


updateOrders

The updateOrders request allows you to update an order in a number of ways. Depending on the parameters used in the request, it's possible to update the order status, add courier and/or tracking information or simply add notes.

Request

Parameters Description Type Required/Optional
ESPOrderNo The Volo order number to update Int Required
OrderStatus Update the order to the defined status. Accepted values are; WAITING_FOR_DELIVERY, DELIVERED, CANCELLED or ON_HOLD String Optional
OnHoldNotes Updates the order status to 'On Hold' and adds an 'On Hold' reason to the order. String Optional
Courier Adds the courier name when the order is marked as delivered. The courier must be available within the 'Courier' dropdown list within the Sales Orders > Order Processing screen. String Optional
CourierService Not currently in use. String Optional
CourierTracking Used to specificy the tracking number for the order. String Optional
Notes Used to add notes internal to orders. String Optional

Example Request

<arg0>
   <OrderUpdate>
      <ESPOrderNo>5381</ESPOrderNo>
      <OrderStatus>DELIVERED</OrderStatus>
      <Courier>Hermes</Courier>
      <CourierTracking>AS12716454YT</CourierTracking>
      <Notes>Marked as shipped</Notes>
   </OrderUpdate>
</arg0>

Example Response

<return>
   <responseMessage>Updated 1 orders.</responseMessage>
   <responseStatus>OK</responseStatus>
   <timestamp>2015-07-07T09:46:21.867+01:00</timestamp>
</return>


getOrderCredits

The getOrderCredits request allows the developer to request Order Credit from within the Volo platform.

Request

Parameters Description Type Required/Optional
arg0 The start date in which to search for Order Credits Date YYYY-MM-DDTHH:MM:SS Optional
arg1 The end date in which to search for Order Credits Date YYYY-MM-DDTHH:MM:SS Optional

Example Request

<arg0>
   <getOrderCredits>
      <arg0>2015-01-01T00:00:00</arg0>
      <arg1>2015-05-01T00:00:00</arg1>
   </getOrderCredits>
</arg0>

Response

Name Description
CreditNoteNumber The Credit Note number for the order
CreditNoteDate The Credit Note date for the order
ShippingRefunded The amount refunded for Shipping on the order
InsuranceRefunded The amount refunded for Insurance on the order
DiscountRefunded The amount refunded for Discount on the order
UnitPrice The Unit price of the item on the order
CancelReason The reason for the order's cancellation
StockNumber The Stock Number of the product being refunded
QuantityRefunded The Quantity of units of stock refunded
OrderNumber The Volo Order Number
InvoiceNumber The Volo Invoice Number
CustomerName The name of the customer from the order

Example Response

<return>
   <responseStatus>OK</responseStatus>
   <timestamp>2015-08-10T09:23:18.078+01:00</timestamp>
   <OrderCreditResponse>
      <OrderCredit>
         <CreditNoteNumber>50000</CreditNoteNumber>
         <CreditNoteDate>2015-08-10+10:00</CreditNoteDate>     
         <ShippingRefunded>0.00</ShippingRefunded>       
         <InsuranceRefunded>0.00</InsuranceRefunded>
         <DiscountRefunded>2015-06-08+01:00</DiscountRefunded>
         <UnitPrice>27.60</UnitPrice>
         <CancelReason>Wrong Size</CancelReason>
         <StockNumber>mag02-single-test</StockNumber>
         <QuantityRefunded>1</QuantityRefunded>
         <OrderNumber>5434</OrderNumber>
         <InvoiceNumber>41441</InvoiceNumber>
         <CustomerName>Example Customer</CustomerName>
      </OrderCredit>
   </OrderCreditResponse>
</return>