List All Products

Only GET and POST queries to all products are supported. To get a list of products, send a GET request to /api/products/:

GET /api/products/

This request returns products with a short list of details for each product.

Get a Specific Product

GET, PUT, and DELETE queries are supported when referring to a particular product.

To get a specific product, send a GET request to /api/products/<product_id>/:

GET /api/products/100

To refer to all products of a particular category send a GET request to /api/categories/:id/products/:

GET /api/categories/166/products/

To refer to to a particular product in a particular category, send a GET request to /api/categories/:id/products/:id:

GET /api/categories/166/products/123

Response Format

  • The product exists: HTTP/1.1 200 OK and JSON with product details.
  • The products doesn’t exist: HTTP/1.1 404 Not Found.

Filtering: an overview

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 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 Store Builder Ultimate or vendor in CS-Cart Multi-Vendor, use the stores and vendors entity respectively:

Store Builder Send a GET request to /api/stores/<company_id>/products/
Multi-Vendor Send a GET request to /api/products/


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:

GET /api/stores/1/products?pfull=Y&price_from=10&sort_by=product&sort_order=asc&q=foo


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
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
Product status:
A for Active
D for Disabled
H for Hidden


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.

Product details

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

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


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
Product status:
A for Active
D for Disabled
H for Hidden
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
exceptions_type Exception type (Allow/ Forbid products with certain option combinations) F
feature_comparison Enable/disable adding the product to a feature comparison list N
free_shipping Allow free shipping 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
lang_code Language code Default language code
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
Out of stock action:
N for None
B for Buy in advance
S for Sign up for notification
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
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
Inventory tracking mode
B for Track
D for do not track
unlimited_download For EDP products: allow or not unlimited downloads 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
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

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

Create a product

Store Builder Send a POST request to /api/stores/<company_id>/products/
Multi-Vendor Send a POST request to /api/products/

To create a new product send a POST request with required fields in JSON: category_ids, products.


Send a POST request to /api/products/:

POST /api/products/

Example JSON: Create a Product

 "product": "Product Name",
 "category_ids": "166",

This request creates a product with a name, a main category ID and a price.

Response Format

  • The product is created: HTTP/1.1 201 Created and JSON with new product ID.
  • If the product wasn’t created, the response will look like this: HTTP/1.1 400 Bad Request.

Update a product

To update an existing product, send the PUT request to /api/products/<product_id>/. For example:

PUT /api/product/100

Example JSON: Update Product details

 "product": "New Product Name",
 "category_ids": "166",
 "amount": "10"

This request updates a Product Name, a main category with id=166, a price and a quantity of the particular product.

Example JSON: Update a Product image

 "product": "Product Name",
 "main_pair": {
 "pair_id": "0",
 "image_id": "0",
 "detailed_id": "0",
  "position": "0",
  "detailed": {
    "image_path": "https://path/to/image.jpg"

This request updates the main image of the particular product. In this example the field main_pair represents the main image of the product and can be a local file on your server. To specify the remote image use the image_path field of the detailed object to specify the URL of the image.

Response Format

  • The product is updated: HTTP/1.1 200 OK and JSON with product_id.
  • Failed to update the product: HTTP/1.1 400 Bad Request.

Delete a product

To delete a product, send a DELETE request to the /api/products/<product_id>. For example:

DELETE /api/products/100/

This request will delete the product with product_id=100.

Response Format

  • The product has been deleted successfully: HTTP/1.1 204 No Content.
  • The product couldn’t be deleted: HTTP/1.1 400 Bad Request.
  • The product doesn’t exist: HTTP/1.1 404 Not Found.