API - Orders

The Orders resource contains several methods that return order specific information.

In addition the createOrder method allows you to POST an order to our system.

Method Name: listOrders, listPreviousOrders, listNextOrders

Retrieve a list of the orders on your account. The list will contain 25 orders at a time with links to the next and previous pages.

The methods listPreviousOrders and listNextOrders are pagination methods.

Method: GET
Parameters:
- Limit — Min Value: 0, Max Value: 25.
- Offset — Min Value: 0
Request Headers: Accept, Authorization, Host
Request Message Body: None
Response Headers: Content-Length, Content-Type, Content-Location
Response Message Body: List of orders
Response Status: 200, 204, 400, 401, 403, 404
Media Types:
- application/vnd.koleimports.ds.order+xml
- application/vnd.koleimports.ds.order+json

Request Parameters:

GET /orders
Host: example.com 
Authorization: Basic {id}:{api_key} 
Accept: application/vnd.koleimports.ds.order+xml

Example CURL Request:

curl -H "Accept: application/vnd.koleimports.ds.order+xml" "https://{id}:{api_key}@api.koleimports.com/orders?limit=1&offset=0"

Example Response:

HTTP/1.1 200 OK 
Content-Type: application/vnd.koleimports.ds.order+xml
Content-Length: 1804
Content-Location: https://api.koleimports.com/orders?limit=25&offset=0

<?xml version="1.0" encoding="utf-8"?>
<orders>
    <order>
        <order_id></order_id>
        <customer_id></customer_id>
        <po_number></po_number>
        <status></status>
        <tax_exempt></tax_exempt>
        <notes></notes>
        <created></created>
        <modified>2011-06-10T15:16:16</modified>
        <received>2011-03-21T07:22:25</received>
        <ship_options>
            <ship_account_id></ship_account_id>
            <carrier></carrier>
            <service></service>
            <signature></signature>
            <instructions></instructions>
            <notifications>
                <notification>
                    <type></type>
                    <email></email>
                </notification>
            </notifications>
        </ship_options>
        <bill_to_address>
            <first_name></first_name>
            <last_name></last_name>
            <company></company>
            <address_1></address_1>
            <address_2></address_2>
            <city></city>
            <state></state>
            <zipcode></zipcode>
            <country></country>
            <phone></phone>
        </bill_to_address>
        <ship_to_address>
            <first_name></first_name>
            <last_name></last_name>
            <company></company>
            <address_1></address_1>
            <address_2></address_2>
            <city></city>
            <state></state>
            <zipcode></zipcode>
            <country></country>
            <phone></phone>
        </ship_to_address>
        <items>
            <item>
                <sku></sku>
                <upc></upc>
                <title></title>
                <weight></weight>
                <quantity></quantity>
                <unit_price></unit_price>
                <type></type>
                <line_status></line_status>
                <line_total></line_total>
            </item>
        </items>
        <invoice>
            <invoice_id></invoice_id>
            <status></status>
            <due>
                <subtotal></subtotal>
                <tax></tax>
                <duty></duty>
                <shipping></shipping>
                <total></total>
            </due>
            <owed>
                <subtotal></subtotal>
                <tax></tax>
                <duty></duty>
                <shipping></shipping>
                <total></total>
            </owed>
            <paid>
                <subtotal></subtotal>
                <tax></tax>
                <duty></duty>
                <shipping></shipping>
                <total></total>
            </paid>
            <refunded>
                <subtotal></subtotal>
                <tax></tax>
                <duty></duty>
                <shipping></shipping>
                <total></total>
            </refunded>
        </invoice>
        <links>
            <link>
                <method></method>
                <media_type></media_type>
                <url></url>
            </link>
        </links>
    </order>
    <links>
        <link>
            <method></method>
            <media_type></media_type>
            <url></url>
        </link>
    </links>
</orders>

Response Field Definitions

The listOrders, listPreviousOrders and listNextOrders methods are collection methods. See getOrder for field definitions.

Method Name: getOrder

Retrieve information about an Order by the Order ID.

Method: GET
Parameters: None
Request Headers: Accept, Authorization, Host
Request Message Body: None
Response Headers: Content-Length, Content-Type, Content-Location
Response Message Body: Order Information
Response Status: 200, 400, 401, 403, 404
Media Types:
- application/vnd.koleimports.ds.order+xml
- application/vnd.koleimports.ds.order+json

Request Parameters:

GET /orders/{order_id}
Host: example.com 
Authorization: Basic {id}:{api_key} 
Accept: application/vnd.koleimports.ds.order+xml

Example CURL Request:

curl -H "Accept: application/vnd.koleimports.ds.order+xml" "https://{id}:{api_key}@api.koleimports.com/orders/{order_id}"

Example Response:

HTTP/1.1 200 OK 
Content-Type: application/vnd.koleimports.ds.order+xml
Content-Length: 1804
Content-Location: https://api.koleimports.com/orders/{order_id}

<?xml version="1.0" encoding="utf-8"?>
<order>
    <order_id></order_id>
    <customer_id></customer_id>
    <po_number></po_number>
    <status></status>
    <tax_exempt></tax_exempt>
    <notes></notes>
    <created></created>
    <modified></modified>
    <received></received>
    <ship_options>
        <ship_account_id></ship_account_id>
        <carrier></carrier>
        <service></service>
        <signature></signature>
        <instructions></instructions>
        <notifications>
            <notification>
                <type></type>
                <email></email>
            </notification>
        </notifications>
    </ship_options>
    <bill_to_address>
        <first_name></first_name>
        <last_name></last_name>
        <company></company>
        <address_1></address_1>
        <address_2></address_2>
        <city></city>
        <state></state>
        <zipcode></zipcode>
        <country></country>
        <phone></phone>
    </bill_to_address>
    <ship_to_address>
        <first_name></first_name>
        <last_name></last_name>
        <company></company>
        <address_1></address_1>
        <address_2></address_2>
        <city></city>
        <state></state>
        <zipcode></zipcode>
        <country></country>
        <phone></phone>
    </ship_to_address>
    <items>
        <item>
            <sku></sku>
            <upc></upc>
            <title></title>
            <weight></weight>
            <quantity></quantity>
            <unit_price></unit_price>
            <type></type>
            <line_status></line_status>
            <line_total></line_total>
        </item>
    </items>
    <invoice>
        <invoice_id></invoice_id>
        <status></status>
        <due>
            <subtotal></subtotal>
            <tax></tax>
            <duty></duty>
            <shipping></shipping>
            <total></total>
        </due>
        <owed>
            <subtotal></subtotal>
            <tax></tax>
            <duty></duty>
            <shipping></shipping>
            <total></total>
        </owed>
        <paid>
            <subtotal></subtotal>
            <tax></tax>
            <duty></duty>
            <shipping></shipping>
            <total></total>
        </paid>
        <refunded>
            <subtotal></subtotal>
            <tax></tax>
            <duty></duty>
            <shipping></shipping>
            <total></total>
        </refunded>
    </invoice>
    <links>
        <link>
            <method></method>
            <media_type></media_type>
            <url></url>
        </link>
    </links>
</order>

Response Body Field Definitions

Field Name	Description	Type	Length
Field Name	Description	Type	Length
order	Children: order_id customer_id po_number status tax_exempt notes created modified received ship_options bill_to_address ship_to_address items invoice links	n/a	n/a
order_id	A unique order number.	integer	10
customer_id	The customer number associated with the account.	string	6
po_number	The purchase order number.	String	20
status	A constant that specifies the order status. Options: PROCESSING, CHARGED, PACKAGING, SHIPPED, HOLD, VOID	String	n/a
tax_exempt	A boolean that dictates whether or not this order exempt from sales tax. Options: 0 or 1	Boolean	1
notes	This field is for order level communication. e.g. Please hold for a week.	String	250
created	The ISO 8601 Timestamp for when the order was created (0000-00-00T00:00:00).	String	19
modified	The ISO 8601 Timestamp for when the order was last modified (0000-00-00T00:00:00).	String	19
received	The ISO 8601 Timestamp for when the order was received and approved (0000-00-00T00:00:00).	String	19
ship_options	Children: ship_account_id carrier service signature instructions	n/a	n/a
ship_account_id	The account number associated with the shipment.	String	20
carrier	A constant that specifies which shipping carrier was used. Options: FEDEX or UPS.	String	n/a
service	A description of the shipping service for this order.	String	60
signature	A boolean that states whether a signature is required upon delivery. Options: 0 or 1	Boolean	1
instructions	This field is for shipping instructions for the carrier. e.g. Please don't ship at night.	String	250
notifications	Children: notification	n/a	n/a
notification	Children: type email	n/a	n/a
type	A constant that specifies the type of notification. Options: TRACKING	String	n/a
email	The email address that will be notified.	String	250
bill_to_address	Children: first_name last_name company address_1 address_2 city state zipcode country phone	n/a	n/a
first_name	Customer first name	String	40
last_name	Customer last name	String	40
company	Customer company name	String	60
address_1	Customer address	String	100
address_2	Customer extended address	String	100
city	Customer City	String	60
state	Customer State. Two-letter state abbreviation. (e.g. CA, NY, VT).	String	2
zipcode	Customer Zipcode	String	5
country	Customer Country Code. Only US and USA supported.	String	3
phone	Customer Phone Number	String	10
ship_to_address	Children: first_name last_name company address_1 address_2 city state zipcode country phone	n/a	n/a
first_name	Recipient first name	String	40
last_name	Recipient last name	String	40
company	Recipient company name	String	60
address_1	Recipient address	String	100
address_2	Recipient extended address	String	100
city	Recipient City	String	60
state	Recipient State. Two-letter state abbreviation. (e.g. CA, NY, VT).	String	2
zipcode	Recipient Zipcode	String	5
country	Recipient Country Code. Only US and USA supported.	String	3
phone	Recipient Phone Number	String	10
items	Children: item	n/a	n/a
item	Children: sku upc title weight quantity unit_price type line_status line_total	n/a	n/a
sku	The 5 Letter SKU of the item.	String	5
upc	The universal product code for the item.	String	20
title	A short description for the item ordered.	String	150
weight	The total weight (in lbs.) for the line.	integer	6
quantity	The number of pieces to order for the item. This quantity must be greater than 0 and in multiple of the items base pack size. This means that if you are ordering a 24 pack of and item, then the quantity is 24.	Integer	6
unit_price	The per piece price for the item.	decimal	10
type	A constant that specifies the type of line item. Options: PRODUCT	String	n/a
line_status	A constant that specifies the status of the line item. Options: ORDERED	String	n/a
line_total	The total price for the item.	decimal	10
invoice	Children: invoice_id status due owed paid refunded	n/a	n/a
invoice_id	The invoice id. This is issued after the order has been processed.	String	6
status	A constant that specifies the invoice status. Options: unpaid, partially paid, paid in full, paid and pending refund, paid and partially refunded, refunded, cancelled, scheduled payment	String	n/a
due	Children: subtotal tax duty shipping total	n/a	n/a
subtotal	The subtotal for the order.	decimal	10
tax	The total tax for the order.	decimal	10
duty	The total duty for the order.	decimal	10
shipping	The total shipping price for the order.	decimal	10
total	The total price for the order.	decimal	10
owed	Children: subtotal tax duty shipping total	n/a	n/a
subtotal	The subtotal still owed for the order.	decimal	10
tax	The tax still owed for the order.	decimal	10
duty	The duty still owed for the order.	decimal	10
shipping	The shipping still owed for the order.	decimal	10
total	The total still owed for the order.	decimal	10
paid	Children: subtotal tax duty shipping total	n/a	n/a
subtotal	The subtotal already paid for the order.	decimal	10
tax	The tax already paid for the order.	decimal	10
duty	The duty already paid for the order.	decimal	10
shipping	The shipping already paid for the order.	decimal	10
total	The total already paid for the order.	decimal	10
refunded	Children: subtotal tax duty shipping total	n/a	n/a
subtotal	The subtotal refunded for the order.	decimal	10
tax	The tax refunded for the order.	decimal	10
duty	The duty refunded for the order.	decimal	10
shipping	The shipping refunded for the order.	decimal	10
total	The total refunded for the order.	decimal	10
links	Children: link	n/a	n/a
link	Children: method media_type url	n/a	n/a
method	The name of the API method.	String	100
media_type	The media type for the method. Use this in the Accept Header.	String	250
url	The URL used to access the resource.	String	250

Method Name: createOrder

This method will take the request body and create an order with it.

The createOrder method has the following pre-requirements:

Your account must have a billing address.
Your account must have at least one payment method.
Your account must have at least one shipping account with either FedEx or UPS.

In Addition, all API accounts are in Test Mode by default. Orders will not be submitted until the account is moved to production mode.

Note: When specifying the quantity to order for a product, the number should be the actual number of pieces in the price tier. This means that if an item comes in packs of 24 and you are you want 1 pack, then the quantity should be 24.

Method: POST
Parameters: None
Request Headers: Accept, Authorization, Content-Type, Host
Request Message Body: Download Sample
Response Headers: Content-Length, Content-Type, Location
Response Message Body: Links to access the newly created resource
Response Status: 201, 400, 401, 403, 500
Media Types:
- application/vnd.koleimports.ds.order+xml
- application/vnd.koleimports.ds.order+json

Request Parameters:

POST /orders
Host: example.com 
Authorization: Basic {id}:{api_key} 
Accept: application/vnd.koleimports.ds.order+xml 
Content-Type: application/vnd.koleimports.ds.order+xml

Example CURL Request:

curl -H "Accept: application/vnd.koleimports.ds.order+xml" \
     -H "Accept: application/vnd.koleimports.ds.order+xml" \ 
     -d <?xml version="1.0" encoding="utf-8"?>
    <order>
        <po_number></po_number>
        <notes></notes>
        <ship_options>
            <carrier></carrier>
            <service></service>
            <signature></signature>
            <instructions></instructions>
        </ship_options>
        <ship_to_address>
            <first_name></first_name>
            <last_name></last_name>
            <company></company>
            <address_1></address_1>
            <address_2></address_2>
            <city></city>
            <state></state>
            <zipcode></zipcode>
            <ext_zipcode></ext_zipcode>
            <country></country>
            <phone></phone>
        </ship_to_address>
        <items>
            <item>
                <sku></sku>
                <quantity></quantity>
            </item>
        </items>
    </order>
"https://{id}:{api_key}@api.koleimports.com/orders"

Request Field Definitions

Below you will find the definitions to all of the fields that are available for the request body.

Field Name	Description	Type	Required	Length
Field Name	Description	Type	Required	Length
order	Children: po_number notes ship_options ship_to_address items	n/a	Yes	n/a
po_number	The purchase order number.	String	No	20
notes	This field is for order level communication. e.g. Please hold for a week.	String	No	250
ship_options	Children: carrier service signature instructions	n/a	Yes	n/a
carrier	A constant that specifies which shipping carrier to use. Options: FEDEX or UPS.	String	Yes	n/a
service	A constant that specifies which shipping service to use. Options: GROUND, PRIORITY or OVERNIGHT	String	Yes	n/a
signature	A boolean that makes a signature required upon delivery. Options: 0 or 1	Boolean	No	1
instructions	This field is for shipping instructions for the carrier. e.g. Please don't ship at night.	String	No	250
ship_to_address	Children: first_name last_name company address_1 address_2 city state zipcode ext_zipcode country phone	n/a	Yes	n/a
first_name	Recipient first name	String	*	40
last_name	Recipient last name	String	*	40
company	Recipient company name	String	*	60
address_1	Recipient address	String	Yes	100
address_2	Recipient extended address	String	No	100
city	Recipient City	String	Yes	60
state	Recipient State. Two-letter state abbreviation. (e.g. CA, NY, VT).	String	Yes	2
zipcode	Recipient Zipcode	String	Yes	5
ext_zipcode	Recipient Extended Zipcode	String	No	4
country	Recipient Country Code. Only US and USA supported.	String	Yes	3
phone	Recipient Phone Number	String	No	10
items	Children: item	n/a	Yes	n/a
item	Children: sku quantity	n/a	Yes	n/a
sku	The 5 character SKU of the item. Alphabetic characters should be in UPPERCASE.	String	Yes	5
quantity	The number of pieces to order for the item. This quantity must be greater than 0 and in multiple of the items base pack size.	Integer	Yes	6

* - First and last name are only required if company name isn't present.

Example Response:

HTTP/1.1 201 OK 
Content-Type: application/vnd.koleimports.ds.order+xml
Content-Length: 1804
Content-Location: https://api.koleimports.com/orders/{order_id}

<?xml version="1.0" encoding="utf-8"?>
<links>
    <link>
        <method>getOrder</method>
        <media_type>application/vnd.koleimports.ds.order+xml</media_type>
        <url>https://api.koleimports.com/orders/**{id}**</url>
    </link>
    <link>
        <method>createOrder</method>
        <media_type>application/vnd.koleimports.ds.order+xml</media_type>
        <url>https://api.koleimports.com/orders/</url>
    </link>
</links>

Response Field Definitions

Below you will find the definitions to all of the fields that are available for the response body.

Field Name	Description	Type	Length
Field Name	Description	Type	Length
links	Children: link	n/a	n/a
link	Children: method media_type url	n/a	n/a
method	The name of the API method.	String	100
media_type	The media type for the method. Use this in the Accept Header.	String	250
url	The URL used to access the resource.	String	250

Section:: Dropship API Documentation
Last Updated:: 01 Nov, 2012 07:12 PM

Recent Articles

	Will Call
	When will my order ship?
	Return Policy
	How Do I Pay For My Order?
	What Types of Products Do We Carry?

	When Will An Item Be Back In Stock?
	Where Can I Get More Information On A Product?
	API Overview
	How will my order ship?
	LTL
	International Shipping
	Who Are We?
	API - Orders
	Do you ship to addresses outside of the USA?
	How To Calculate The Shipping Cost For An Order

API - Orders

Method Name: listOrders, listPreviousOrders, listNextOrders

Request Parameters:

Example CURL Request:

Example Response:

Response Field Definitions

Method Name: getOrder

Request Parameters:

Example CURL Request:

Example Response:

Response Body Field Definitions

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Children:

Method Name: createOrder

Request Parameters:

Example CURL Request:

Request Field Definitions

Children:

Children:

Children:

Children:

Children:

Example Response:

Response Field Definitions

Children:

Children:

Recent Articles