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