Order

  • Updated
Follow

Overview

Order is an object used in Versa for Sales, Purchase, RMA, Transfer Orders. Order has many order items.

Order has a order type id assigned to it. The possible values for order type id is 1 for purchase order, 2 for sales order, 3 for transfer order, 4 for RMA order.

 

Format of any request that is not get should be JSON. For get request, you can use XML or JSON.

Examples are provided in XML/JSON  and in CURL command format.
 
api_url depends on which host your account is assigned to. It will be the same URL you log in with
.
URL https://api_url/v1/order
Supported Methods GET, POST, DELETE
Description Retrieve, Create or Delete the firm's Sales Orders

Accepted Query Formats

GET /order[.format] retrieve all orders
GET /order/1[.format] retrieve order with ID = 1
GET /order[.format]?order_type_id=2 retrieve all sales orders
GET /order[.format]?order_type_id=1 retrieve all purchase orders
GET /order[.format]?order_number=123 find a purchase order or sales order with order number
DELETE /order/1 delete order with ID = 1
GET /order/open[.format] retrieve all open sales orders
POST /order[.format] create a new order
POST /order/1/ship_order[.format] Ship products from order

Filters

You can use different filters on the order API. Chain different filters using & .

order_type_id: User 2 to get sales order and 1 to get purchase orders.
order_number: Find a order by order number
since_id: Find all order with a id that is larger than the passed in id
updated_at: Find all orders updated since updated_at time.  The time should be in this format 2016-06-01 00:00 . Apply time zone with this 2016-06-01 00:00-07

customer_id: Find orders for a specific customer. The customer ID is an internal unique id assigned to each customer.

customer_identifier: Find orders for a specific customer using the identifier which is a field associated with customers.

start_date: Find all orders with an order date that equals or after the start_date

end_date: Find all orders with an order date that equals or before the end_date

acknowledged: Pass in either 1, true, false, or 0. Get a list of order that have not been acknowledged. See the method acknowledge on how to acknowledge an order. 

Examples

Retrieve all orders in XML format:

$ curl -i --header "VERSACCOUNTS_AUTHORIZATION:409696900e0b3f5a4297e3cd5823f734f0095e66" https://api_url/v1/order.xml

Retrieve all open sales orders in XML format:

$ curl -i --header "VERSACCOUNTS_AUTHORIZATION:409696900e0b3f5a4297e3cd5823f734f0095e66" https://api_url/v1/order/open.xml

Retrieve all open orders in XML format with pagination and since_id. since_id is used to find orders with ids large than since_id. Use since_id parameter if you have already fetched orders in the past and wish to only get orders created since last fetch.

$ curl -i --header "VERSACCOUNTS_AUTHORIZATION:409696900e0b3f5a4297e3cd5823f734f0095e66" 'https://api_url/v1/order/open.xml?since_id=123&page=2'

Retrieve a single order in XML format:

$ curl -i --header "VERSACCOUNTS_AUTHORIZATION:409696900e0b3f5a4297e3cd5823f734f0095e66" https://api_url/v1/order/2040.xml


<?xml version="1.0" encoding="UTF-8"?>
<orders type="array">
  <order>
    <id type="integer">2040</id>
    <order-date type="date">2012-10-19</order-date>
    <multiplier type="decimal">1.0</multiplier>
    <customer-bill-to-id type="integer">1550</customer-bill-to-id>
    <ship-to-party-id type="integer">5444</ship-to-party-id>
    <order-number type="integer">109</order-number>
    <firm-id type="integer">159</firm-id>
    <message>Colour & Texture : Almond Smooth</message>
    <ship-to>
      <party>
        <company-name>Laplace Tranformational Homes</company-name>
        <surname>Ray</surname>
        <given-name>Chen</given-name>
        <address-line-1>440 Spectrum Ave</address-line-1>
        <address-line-2></address-line-2>
        <address-line-3></address-line-3>
        <postal-zip-code></postal-zip-code>
        <contact-number-1>604-123-1234</contact-number-1>
        <contact-number-2></contact-number-2>
        <email></email>
        <province-state>BC</province-state>
        <city>Vancouver</city>
        <country>Canada</country>
      </party>
    </ship-to>
    <currency>
      <id type="integer">1</id>
      <name>Canadian dollar</name>
    </currency>
    <payment-terms>
      <id type="integer">188</id>
      <discount type="integer">0</discount>
      <discount-period type="integer">0</discount-period>
      <net type="integer">0</net>
      <text>0% 0  /  Net 0 days</text>
    </payment-terms>
    <bill-to>
      <party>
        <company-name>Coyote Dream Homes</company-name>
        <surname>Wile E.</surname>
        <given-name>Coyote</given-name>
        <address-line-1>123 Canyon Way</address-line-1>
        <address-line-2></address-line-2>
        <address-line-3></address-line-3>
        <postal-zip-code></postal-zip-code>
        <contact-number-1>604.123.1234</contact-number-1>
        <contact-number-2></contact-number-2>
        <email></email>
        <province-state>BC</province-state>
        <city>Vancouver</city>
        <country>Canada</country>
      </party>
    </bill-to>
    <order-items type="array">
      <order-item>
        <product-id type="integer">430</product-id>
        <quantity type="integer">1</quantity>
        <measurement-unit-id type="integer">1191</measurement-unit-id>
        <estimated-delivery-date type="datetime">2013-01-14T00:00:00Z</estimated-delivery-date>
        <per-unit-cost>31410.38</per-unit-cost>
        <measurement-unit-name>EA</measurement-unit-name>
        <practical-name>Cast Stone Lite</practical-name>
        <line-item type="integer">1</line-item>
        <note-a>Please see the attached Schedule A for the detailed break-down</note-a>
        <note-b>This item is non-returnable</note-b>
        <order-item-applied-taxes type="array">
          <order-item-applied-tax>
            <tax-id type="integer">291</tax-id>
            <amount type="decimal">3392.32</amount>
            <description>LineItemValue x HST</description>
          </order-item-applied-tax>
        </order-item-applied-taxes>
        <order-item-adjustments type="array">
          <order-item-adjustment>
            <adjustment-type-id type="integer">289</adjustment-type-id>
            <percentage type="decimal">-10.0</percentage>
            <amount nil="true"></amount>
            <adjustment-type>
              <name>Discount</name>
            </adjustment-type>
          </order-item-adjustment>
        </order-item-adjustments>
      </order-item>
    </order-items>
    <sales-order-channel>
      <id type="integer">2</id>
      <channel-name>Web Store</channel-name>
    </sales-order-channel>
    <sales-agent>
      <id type="integer">1</id>
      <party>
        <company-name>Paragon Sales Inc.</company-name>
        <surname></surname>
        <given-name></given-name>
        <address-line-1></address-line-1>
        <address-line-2></address-line-2>
        <postal-zip-code></postal-zip-code>
        <contact-number-1></contact-number-1>
        <contact-number-2></contact-number-2>
        <email></email>
        <province-state></province-state>
        <city></city>
      </party>
    </sales-agent>
  </order>
    ...
  <order>
    ...
  </order>
</orders>


Create a new order with order type of 2 which is sales order, response in XML format:

$ curl -X POST -H "Content-Type: application/json" -d @new_order.json -i --header "VERSACCOUNTS_AUTHORIZATION:494d60c5b140f1900e04256eca0d599cc0214fcf" https://api_url/v1/order

Posted JSON file:

{
"order": {
"external_order_reference_number": "A-12345",
"order_date": "2012-10-19",
"order_type_id": 2,
"currency_id": "1",
"multiplier": "1.0",
"customer_bill_to_id": "1550",
"ship_to_party_id": "5444",
"message": "",
"term_id": "188"
}
}

Response:

<?xml version="1.0" encoding="UTF-8"?>
<orders type="array">
  <order>
    <id type="integer">2167</id>
    <order-date type="date">2012-10-19</order-date>
    <multiplier type="decimal">1.0</multiplier>
    <customer-bill-to-id type="integer">1550</customer-bill-to-id>
    <ship-to-party-id type="integer">5444</ship-to-party-id>
    <order-number type="integer">115</order-number>
    <firm-id type="integer">159</firm-id>
    <message>Colour & Texture : Almond Smooth</message>
    <ship-to>
      <party>
        <id type="integer">5444</id>
        <company-name>Kellogs Dream Homes</company-name>
        <surname>Ray</surname>
        <given-name>Chen</given-name>
        <address-line-1>4639 Simpsons Ave</address-line-1>
        <address-line-2></address-line-2>
        <address-line-3></address-line-3>
        <postal-zip-code></postal-zip-code>
        <contact-number-1>604-562-8339</contact-number-1>
        <contact-number-2></contact-number-2>
        <email></email>
        <province-state>BC</province-state>
        <city>Vancouver</city>
        <country>Canada</country>
      </party>
    </ship-to>
    <currency>
      <id type="integer">1</id>
      <name>Canadian dollar</name>
    </currency>
    <payment-terms>
      <id type="integer">188</id>
      <discount type="integer">0</discount>
      <discount-period type="integer">0</discount-period>
      <net type="integer">0</net>
      <text>0% 0  /  Net 0 days</text>
    </payment-terms>
    <bill-to>
      <id type="integer">1550</id>
      <party>
        <id type="integer">5204</id>
        <company-name>Coyote Dream Homes</company-name>
        <surname>Wile E.</surname>
        <given-name>Coyote</given-name>
        <address-line-1>123 Canyon Way</address-line-1>
        <address-line-2></address-line-2>
        <address-line-3></address-line-3>
        <postal-zip-code></postal-zip-code>
        <contact-number-1>604.123.1234</contact-number-1>
        <contact-number-2></contact-number-2>
        <email></email>
        <province-state>BC</province-state>
        <city>Vancouver</city>
        <country>Canada</country>
      </party>
    </bill-to>
    <nil-classes type="array"/>
  </order>
</orders>

Delete an order:

$ curl -X DELETE -i --header "VERSACCOUNTS_AUTHORIZATION:494d60c5b140f1900e04256eca0d599cc0214fcf" https://api_url/v1/order/2166

Response:

Order destroyed
Ship order
This is used to indicate order items in an order has been shipped.
 
$ curl -X POST -H "Content-Type: application/xml" -d new_order.xml -i --header "VERSACCOUNTS_AUTHORIZATION:494d60c5b140f1900e04256eca0d599cc0214fcf" https://api_url/v1/order/123/ship_order.xml

Posted XML file:

<?xml version="1.0" encoding="UTF-8"?>
<order>
  <effective-date>2030-01-01</effective-date>
  <auto-post-invoice">false</auto-post-invoice>
  <auto-apply-deposit>false</auto-apply-deposit>
  <auto-create-invoice>true</auto-create-invoice>
  <tracking_number>123</tracking_number>
  <weight>1</weight>
  <weight_unit_type>lb</weight_unit_type>
  <height>2</height>
  <width>1</width>
  <depth>2</depth>
  <dimension_unit_type>inch</dimension_unit_type>
  <actual_shipping_cost>12.23</actual_shipping_cost>
  <shipping_carrier_id>2</shipping_carrier_id>
  <shipping_carrier_service_description>Fedex 2 Day</shipping_carrier_service_description>
  </order>

<order-items type="array">
      <order-item>
        <id>430</id>
        <quantity>1</quantity>
        <lot-id></lot-id>
        <lot-number></lot-number>
        <serial-number></serial-number>
      </order-item>
    </order-items>
</order>

acknowledge an order:

This is used by API client to acknowledge download of an order. Pass in the filter acknowledged=1 when getting a list of orders will filter out any order that has been acknowledged.

Use the filter acknowledged=1 to pull a list of all orders not acknowledged.

 

$ curl -X POST -H "Content-Type: application/json" -i --header "VERSACCOUNTS_AUTHORIZATION:494d60c5b140f1900e0425eca0d599cc0214fcf" https://api_url/v1/order/123/acknowledge

 

Help

Was this article helpful? 0 out of 0 found this helpful
Have More Questions?
Submit a Request or Create a New Post
Return to top

Comments and Suggestions

0 comments

Please sign in to leave a comment.

Related articles