Topics

See more

Order

  • Updated
Follow

Overview

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

 

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 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, 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",
"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