Starting from version 4, CS-Cart provides an API to interact with a store.
CS-Cart API:
Is RESTful
Uses Basic HTTP authentication, with admin e-mail as login and auto-generated API key as password
Relies on user group-defined privileges. User group assignment is defined directly in the objects
Uses HTTP 1.1 to implement REST.
4 methods are available to view and modify objects:
GET
—get object dataPUT
—update object dataPOST
—create new objectDELETE
—delete objectAccepts and returns data in JSON format
cURL is a cross-platform command line application that allows you to easily send HTTP requests. In UNIX-based systems, it is usually available by default with a simple curl
command.
Note
All examples in this guide are given as cURL commands.
REST Console is an extension for the popular Google Chrome browser. Similar extensions exist for all popular web-browsers.
API access is activated/disabled on a per-user basis.
To activate API access for a user:
The automatically generated API key will be used by this user along with their e-mail to access the API.
An API request is a regular HTTP request sent to a particular URL.
By default, CS-Cart uses API 1.0 with the URLs built as follows:
For example, http://example.com/api/product/1/features refers to all the features of the product with the ID 1.
Note
If mod_rewrite
is disabled on the server where the target CS-Cart store is installed, you will have to use different URLs:
Nonetheless, API 2.0 is recommended. In API 2.0 the URLs have the following structure:
Each request must be authenticated with user’s e-mail and API key. There are 3 ways to submit authentication data in an API request:
Via the --user
parameter (this is used in all the examples):
curl --user [email protected]:APIkey -X GET 'http://example.com/api/users/'
Inline passing in the URL:
curl --basic -X GET 'http://admin%40example.com:[email protected]/api/users/'
Note
@
must be replaced with %40
In the request header:
curl --header 'Authorization: Basic <base64-encoded email:APIkey pair>=' -X GET 'http://example.com/api/users/'
Note
The email:APIkey pair must be encoded in base64.
PHP example:
$token = base64_encode("email:APIkey");
$authHeaderString = 'Authorization: Basic ' . $token;
GET
)¶To get object data, send a GET
HTTP request to the URL that refers to the according object.
Get data about the product with the ID 1:
curl --user [email protected]:APIkey -X GET 'http://example.com/api/products/1'
It is possible to send additional URL parameters to particularize the selection.
For example, you get all products with non-free shipping:
curl --user [email protected]:APIkey -X GET 'http://example.com/api/products?free_shipping=N'
You can combine conditions.
Get all downloadable products with company_id
1:
curl --user [email protected]:APIkey -X GET 'http://example.com/api/products?is_edp=Y&company_id=1'
JSON array of matching objects (e.g. the products
key) and the search query (the search
key), or an error.
The matching objects value is an array of object IDs as keys and object field arrays as values.
Refer to the API objects page for a complete list of supported fields for all supported objects.
PUT
)¶To update object data, send a PUT
HTTP request to the URL that refers to the according object.
Only URLs referring to particular object IDs can be used (i.e. you cannot update all products at once.)
The submitted data must be a JSON array of keys and values for the object fields (e.g. {'fieldName1: value1, fieldName2: value2}
.)
Refer to the API objects page for a complete list of supported fields for all supported objects.
Important
The header Content-Type
must be declared and set to application/json
, otherwise the default text/plain
is assumed and the request will fail.
Update name of the product with the ID 1:
curl --user admin@example.com:APIkey --header 'Content-Type: application/json' -d '{"product": "New Product Name"}' -X PUT 'http://example.com/api/products/1'
POST
)¶To create an object, send a POST
HTTP request to the URL that refers to the according object type.
Only URLs referring to a whole object type (without ID) can be used.
The submitted data must be a JSON array of keys and values for the object fields (e.g. {'fieldName1: value1, fieldName2: value2}
.)
Some fields are mandatory for object creating. Refer to the API objects page for a complete list of supported fields for all supported objects.
Important
The header Content-Type
must be declared and set to application/json
, otherwise the default text/plain
is assumed and the request will fail.
Create a new product with the name “My Awesome Product”:
curl --user [email protected]:APIkey --header 'Content-Type: application/json' -d '{"product": "My Awesome Product"}' -X POST 'http://example.com/api/products'
DELETE
)¶To delete an object, send a DELETE
HTTP request to the URL that refers to the according object.
Only URLs referring to particular object IDs can be used (i.e. you cannot delete all products at once.)
Delete the product with the id 12:
curl --user [email protected]:APIkey -X DELETE 'http://example.com/api/products/12'
Nothing in response, independently on the success of the operation.
Questions & Feedback
Have any questions that weren't answered here? Need help with solving a problem in your online store? Want to report a bug in our software? Find out how to contact us.