Products

URLs

Nested Objects

Filtering

In order to get products based on a filter, you can use one of the available filters. Product filtering is similar to the advanced search performed in the admin panel.

The request URL is as follows (separated into several lines for readability):

<filter>=Y&
<additional_param>=<value>&
<another_param>=<value>&
...
sort_by=<sorting>&
sort_order=<sort_order>&
q=<query>
  • filter is one of the available filters. It is possible to use any number of filters at a time by appending the URL with &<another_filter>=Y
  • additional_param is one of the available additional params. It is possible to use any number of additional params at a time by appending the URL with &<another_param>=<value>
  • sorting is one of the available sortings
  • sort_order is the sort direction; asc or desc for ascending and descending accordingly
  • query is the search query

In order to get results referring only to a particular store in CS-Cart Ultimate or vendor in CS-Cart Multi-Vendor, use the stores and vendors entity respectively:

Example

Get all products of the 1st store, with ‘foo’ in their full description, costing over $10, and sort the result by product name from A to Z:

curl --user admin@example.com:APIkey -X GET 'http://example.com/api/stores/1/products?pfull=Y&price_from=10&sort_by=product&sort_order=asc&q=foo'

Filters

Available filter attribute values:

Filter Description
pname Product name
pshort Short description
pfull Full description
pkeywords Meta keywords
pcode Product code
cid Category ID
amount_from In stock lower range
amount_to In stock higher range
price_from Price lower range
price_to Price higher range

Additional Params

Param Description Supported values
subcats Include subcategories of the given category (the cid filter must be used) in the search scope
Y
N
order_ids IDs of the orders to search the products in Comma-separated list of order IDs, e.g. 1,13,24
free_shipping Free shipping
Y
N
status
Product status:
A for Active
D for Disabled
H for Hidden
A
D
H

Sorting

Sort param Description
status Product status
list_price List price
product Product name
price Price
code Product code
amount In stock amount

It is possible to set the sort order by defining the sort_order URL param to asc or desc.

Fields

A product has a number of properties, represented by fields.

The full list of supported fields is given below (mandatory fields are marked with *).

Note

Any field not listed in the table below will be ignored if occurs in an API request JSON data.

Field name Description Default value Supported values
product* Product name string
category_ids* IDs of the categories to which the product belongs Array of valid category IDs
main_category* ID of the main category Existing category ID
price* Price 0 float
company_id* ID of the store or vendor the product belongs to Default company ID integer
status*
Product status:
A for Active
D for Disabled
H for Hidden
A
A
D
H
amount Product amount in stock 1 integer
avail_since Date from which the product is available Date in UNIX format
box_height Box height 0 integer
box_length Box length 0 integer
box_width Box width 0 integer
details_layout Product details page layout ‘default’ Valid product template name
edp_shipping Only for a downloadable product: Enable/disable shipping N
Y
N
exceptions_type Exception type (Allow/ Forbid products with certain option combinations) F
A
F
feature_comparison Enable/disable adding the product to a feature comparison list N
Y
N
free_shipping Allow free shipping N
Y
N
full_description Full product description ‘’ string
image_pairs Additional image pairs empty array object with image pair ID as key and image pair as value (see below)
is_edp Downloadable or not N
Y
N
lang_code Language code Default language code
en
ru
etc.
list_price Manufacturer suggested price 0 float
list_qty_count Number of items in the quantity select box 0 integer
localization String of comma-separated localization IDs ‘’ string
low_avail_limit Minimal availability in stock value 0 integer
main_pair Full image and thumbnail pair empty array Main pair object (see below)
max_items_in_box Maximal number of items per box 0 integer
max_qty Maximal order quantity 0 integer
meta_description Meta description ‘’ string
meta_keywords Meta keywords ‘’ string
min_items_in_box Minimal number of items per box 0 integer
min_qty Minimal order quantity 0 integer
options_type Apply options simultaneously (P) or sequentially (S) P
S
P
out_of_stock_actions
Out of stock action:
N for None
B for Buy in advance
S for Sign up for notification
N
N
B
S
page_title Product page title ‘’ string
point_price Price in reward points 0 float
popularity Product popularity rating based on views, adding to cart, and purchases 3 integer
product_code Product code ‘’ string
product_features Product features empty array object that contains product features with feature ID as key and feature data as value
product_id Product ID Set automatically integer
promo_text Promo text ‘’ string
qty_step Quantity step 0 integer
return_period Return period in days 10 integer
sales_amount Sales amount 0 integer
search_words Search keywords for the product ‘’ string
seo_name SEO name for the product page ‘’ string
shared_product Shared or not N
Y
N
shipping_freight Shipping freight 0 float
shipping_params Aggregated shipping data Auto-generated string based on the shipping data string
short_description Short description ‘’ string
tax_ids Array of tax IDs empty array array
timestamp Creation timestamp Set automatically Valid timestamp in UNIX format
tracking
Inventory tracking mode
B for Track
D for do not track
B
B
D
unlimited_download For EDP products: allow or not unlimited downloads N
Y
N
updated_timestamp Last update timestamp Last update timestamp in seconds Valid timestamp in UNIX format
usergroup_ids User group IDs ‘0’ String of comma-separated user group IDs
weight Weight 0 float
zero_price_action
Zero price action
R for Do not allow customers to add product to cart
P for Allow customers to add product to cart
A for Ask customer to enter the price
R
R
P
A

Main Pair

A pair of the full product image and (optionally) a thumbnail.

Field name Description Default value Supported values
detailed_id ID of the full image Set automatically integer
image_id ID of the thumbnail 0 integer
pair_id ID of the image pair Set automatically integer
position Position of the image pair among others 0 integer
icon Thumbnail data object (similar to detailed, see below)
detailed Full image data object (content explained below)
absolute_path Absolute filesystem path to the image Valid filesystem path
alt Alternative text (show if the image fails to load) ‘’ string
http_image_path HTTP path to the image Valid HTTP URL pointing to the image
image_path Actual image path (HTTP or HTTPS; may be the same as http_image_path) Valid URL pointing to the image
image_x Image width in pixels integer
image_y Image height integer