to Kole Imports

Home → Knowledge Base → Dropship API Documentation →

API Overview

The Kole Imports API provides your application to interact with our application, programmatically. This includes access to products, orders, shipments, and account information.

This documentation provides information that developers and programmers require to integrate the API into your online store.

The API adheres to the principles of a RESTful design architecture. Using XML or JSON, requests are made to resources using four of the HTTP Verbs (GET, POST, PUT, DELETE) and responses are delivered back to the client. Using custom media types, hypermedia constraints, and other tenets of RESTful design, the Kole Imports API was built so that it could absorb improvements with minimal changes to the client.

Currently, the API only supports Drop shipping customers. An account is required on http://dropship.koleimports.com

Conventions

To make things easier to understand, the following conventions are used:

  • {text} : Replace text with your own data
  • REQUIRED : The direction must be followed or the API will not work.
  • ... : Representation data has been omitted for the sake of brevity

Test Mode vs. Production Mode

When created, all API Keys are in test mode.

Test mode allows you to work through the development phase without having to worry about making permanent changes or placing orders.

When the development phase is over and the client is ready to move into production, please contact us and we will help you with the rest of the process.

Authentication

Most of the data that can be accessed via the Kole Imports API is sensitive in nature. We take our customers privacy very seriously.

API Authentication is REQUIRED for all requests. It's implemented as HTTP Basic Authentication over SSL (https).

Note: Your API credentials are not the same as the credentials used on the website.

How to obtain API Credentials

There are a couple of prerequisites before authentication will work.

  • Account must have an address associated with it.
  • At least one payment method must be set up.

Once those two requirements are fufilled, follow the instructions below to obtain an API key.

  1. Log in to your account.
  2. From the dashboard, click on the "Account" tab.
  3. Scroll down to the "API Keys" section.
  4. Click "Add a new API Key".

How to Authenticate

The user name is the Account ID found on the Account page and the password is one of your generated API Keys. This approach allows a user to remove a key if they suspect abuse.

Authentication Example

From a Linux command line, type:

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

Learn more about CURL

Entry Point

The entry point URL is

https://api.koleimports.com`

Clients should not make any assumptions about URI layout. All resources will be available from that single entry point.

Note: HTTPS is REQUIRED on every request.

Rate Limiting

Clients are allowed to make up to 1000 requests per hour. These limits are subject to change at any time, without notice.

If for some reason a higher limit is required, please [contact us][].

Media Types

Resource representations and request bodies (when applicable) are encoded in XML or JSON.

Each representation has it's own media type. Further down this document the appropriate media type will be given for each resource but in general they follow a pattern.

XML

application/vnd.koleimports.ds.**{resource}**+xml

JSON

application/vnd.koleimports.ds.**{resource}**+json

The media type is required in the HTTP Accept header (in requests) and Content-Type header (where applicable) in both requests and responses.

Generic Media Types

We do not support the generic media types

application/xml and application/json

If a request is made without the appropriate media types, the API will serve up the most recent xml representation available for the resource. If the client does not adhere to the principle of content negotiation, we cannot guarantee predictable responses.

Request Headers

Header Supported Values Description of Use Required

Accept

Media type describing
the desired response
message body.

Indicates to the server
what media type this
client is prepared to accept.

Yes

Authorization

Basic Authentication
Username and Password

Identifies the authorized
user making this request.

Yes

Content-Length

Length (in bytes) of
the request message body.

Describes the size of
the message body.

Yes, on requests that
contain a message body.

Content-Type

Media type describing
the request message body.

Describes the representation
and syntax of the
request message body.

Yes, on requests that
contain a message body.

Request Data

Request data can be sent in either XML or JSON with the appropriate media type in the Content-Type header.

URI Parameters should only be assumed when specifically noted in the corresponding resources documentation.

Debugging

Below are some handy debugging tools.

Response Headers

Header Supported Values Description of Use Required

Location

Canonical URI of
a newly created
resource.

Returns a new URI
that can be used to
request a representation
of the newly created
resource.

Yes, on responses
to requests that
create new server side
resources accessible via
a URI.

Content-Length

Length (in bytes) of
the response message body.

Describes the size of
the message body.

Yes, on responses that
contain a message body.

Content-Type

Media type describing
the response message body.

Describes the
representation and syntax
of the response message body.

Yes, on responses that
contain a message body.

Content-Location

Canonical URI of a the
response entity.

Describes the resource
location for the entity
enclosed in the message body.

Yes, on responses that
contain a message body.

Response Data

A response message body will be received in either XML or JSON according to the appropriate media type specified in the Accept header of the request.

Note: Timestamps that appear in responses all conform to the ISO 8601 standard.

HTTP Status Codes

Code Status Description

200

Ok

The request was successfully completed. If this request created a new resource that is
addressable with a URI, and a response body is returned containing a representation of
the new resource, a 200 status will be returned with a Location header containing the
canonical URI for the newly created resource.

201

Created

A request that created a new resource was completed, and no response body containing a
representation of the new resource is being returned. A Location header containing the
canonical URI for the newly created resource should also be returned.

202

Accepted

The request has been accepted for processing, but the processing has not been completed.
Per the HTTP/1.1 specification, the returned entity (if any) SHOULD include an indication of the
request's current status, and either a pointer to a status monitor or some estimate of when
the user can expect the request to be fulfilled.

204

No Content

The server fulfilled the request, but does not need to return a response message body.

400

Bad Request

The request could not be processed because it contains missing or invalid information
(such as validation error on an input field, a missing required value, and so on).

401

Unauthorized

The authentication credentials included with this request are missing or invalid.

403

Forbidden

The server recognized your credentials, but you do not possess authorization to
perform this request.

404

Not Found

The request specified a URI of a resource that does not exist.

405

Method Not Allowed

The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported
for this request URI.

406

Not Acceptable

The resource identified by this request is not capable of generating a representation
corresponding to one of the media types in the Accept header of the request.

409

Conflict

A creation or update request could not be completed, because it would cause a conflict
in the current state of the resources supported by the server (for example, an attempt to create
a new resource with a unique identifier already assigned to some existing resource).

500

Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling
the request.

501

Not Implemented

The server does not (currently) support the functionality required to fulfill the request.

503

Service Unavailable

The server is currently unable to handle the request due to temporary overloading
or maintenance of the server.

Application Level Error Codes

When possible, in addition to standard HTTP Status Codes, the response will supply the client with application level error codes and a brief message describing the problem.

Code Description

40001

Request body is malformed or missing.

40002

The ship option carrier field is required. Options include FEDEX or UPS.

40003

The ship option service field is required. Options include GROUND, PRIORITY or OVERNIGHT.

40004

The ship to company name or first and last name is required.

40005

The ship to address is required.

40006

The ship to city is required.

40007

The ship to state (two letter abbreviation) is required.

40008

The ship to zipcode is required.

40009

The ship to country is required.

40010

The request requires at least one product.

40011

One or more of the products are missing the SKU.

40012

The account needs more configuration.
Please log in to the dashboard and set up your account.

40013

The account needs more configuration.
Please log in to the dashboard and set up at least one payment method.

40014

The account needs more configuration.
Please log in to the dashboard and set up at least one shipping account.

40040

The following field is either incorrect or missing: {field_name}

40041

The ship to state is invalid.

40042

The ship to zipcode is invalid. It should contain 5 numeric digits.

40043

The ship to zipcode extension is invalid. It should contain 4 numeric digits.

40044

The ship to country is invalid.

40045

The ship to phone is invalid.

40046

The following item SKU is invalid: {sku}

40047

The following SKU has an invalid quantity: {sku}

40048

One or more of the items are not available for purchase.

40049

The following SKU has an invalid pack size: {sku}

40080

The following item in not available for purchase: {sku}

40081

The order has been rejected by the system.
If this error persists please contact administrator.

40082

The ship to address has been rejected by the system.
If this error persists please contact administrator.

Is this article helpful?

Section:
Dropship API Documentation
Last Updated:
06 Mar, 2014 03:16 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
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