Products - API Reference

When Getting data, if supplying an ID, then only 1 data JSON element is returned. Otherwise an array is returned, irrespective of how many items are matched. When POSTing data, then only a single element will be returned, and only a single element is expected to be POSTed as a time.

Get Parameters

Useful use cases

1. Get all products

Return all products related to your website. Use GET to retrieve the data. Use additional parameters above. Use pagination if you have more than 100 products to return.

Example URL: https://api.cms-tool.net/webapps/api/product

1b. Get 1 product

Return 1 product, with all additional meta data. Use GET to retrieve the data. In this case, data is a single object. 

Example URL: GET https://api.cms-tool.net/webapps/api/product?id=12345

{

"data": 

{

"p_title": "prod1",

"p_price":  10.00,

"pid": 12345,

...

}

}

2. Create a new product

To create a new product you do not need to include an id in the data JSON. All the other information provided will be used to create a new Product.

To add the product to an existing category include : "p_groupid" : group id number. where the group id number can be found from the category endpoint.

{

   "p_title": "Bag",

   "p_price": 50.00,

   "p_qtyinstock": 25.0

}

The above JSON will create a new product with name Bag, price 50 and quantity in stock 25.

3. Update an existing product

To update an existing product include the product id and the fields you would like to update in the data JSON value. Only provide the minimal fields you would like to update in the data. You can also update a product by providing only a p_code instead of an ID, however, it will only update the first match.

In this example, we already know the ID, and only update stock count and price.

{
    "id": 12345,
    "p_qtyinstock": 5.000,
    "p_price": 25.00
}

Product Options

Some Products have sizes/colours/styles associated with it. We can create new options and update existing options for a Product.
To do so, include a JSON Array of styles/colours/sizes and provide p_option_type, p_option keys. The option name is p_option and the option type is p_option_type. The type is optional here while the name has to be unique.
To update any option include the option_id to identify the option to update. See below examples.

1. View Product options

To view the product options related to an individual product, GET the Product using the product ID

Example URL: https://api.cms-tool.net/webapps/api/product?id=12345

The product options will be contained in one of the 3 array elements, highlighting it's type. If the product contains variants, there is no guarantee that the sizes/colours/styles will be represented here, as our system can generate that data on the fly from the variant data.

{
  "id": 12345,
  ...
  "DisplayOptions": {
    "p_sizes": [
       {
           "option": "small"
       },
       {
           "option": "normal"
       },
       {
           "option": "large"
       }
    ],
    "p_colours": [...],
    "p_styles": [...],
    ....
  }
  ...
} 

2. Create/Update options/sizes/colours/styles

To update any option list, please provide an array of json objects (a complete list), where at least "option" is provided. The below example replaces the size list for product 12345.

{
 "id": 12345,
 "DisplayOptions": {
    "p_sizes": [
       {
           "option": "small"
       },
       {
           "option": "normal"
       },
       {
           "option": "large",
           "cost": 10.00,
           "img": "/images/swatchImage.jpg"
       }
   ]
 }
}

3. Deleting options/sizes/colours/styles

The API needs to provide a complete list of options, if any option list is provided. 

If you provide an incomplete array, then this will replace the old option list (thus deleting any that were excluded)

If you provide an empy array or set the array to null, then this will delete that option list. 

If you do not provide the key for the array, then no changes are made. 

The parameter "DeleteMissingArrayElements" has no meaning in this area. 

Product Variants

Product variants are different type of product options as they give you control over the stock quantity of the variation. Creating and updating a variant is similar to product with the key difference that a variant has a parent id. 

1. Insert a Product Variant

To create a new variant provide the variant(s) in the "variants" array. Every variant must have a parent id and hence the id key field must be provided. In the below example we are creating a new variant Large Red variant under the product id 12345. The rest of the information will be used to create the variant.

   "id": 12345,
   "variants": [ 

{

   "id": 12345,

   "variants": [

       {

           "p_size": "Large",

           "p_colour": "Red",

           "p_qtyinstock": 10,

           "p_price": 15.00,

           "p_code": "ABC123",

           "p_img": "image_url.jpeg"

       },

  ...

   ]

}

2. Update Product Variant

To update a variant include the id of the variant or the code to identify the variant. You must also provide the parent id of the variant. All the information provided with it will be used to update the variant. In the below examples we are updating the variant using id in the left example and using the code in the right.

3. Delete Product Variant 

Set the product order status to delete a specific variant. That variant may remain in the database, but it will not be visible to anyone. 

eg  "p_order":-999 

Or, add a request parameter, or a json data parameter (in top level) called "DeleteMissingArrayElements" and we will delete any items that are not in your array.  {Feature under construction}

Pro Tips: 

GST Pricing

Prices via API excl GST, and using 3 decimal points is good to ensure tidy round inclusive pricing. We don't have a GST component field, so if you want inclusive = 12.00, then you need to push price=10.435 Alternatively we can "round" all prices to 10cents if the merchant wants.

Category Ordering

Products can exist in multiple categories. The category exposure is visible or managed in 2 different ways. The hard connection to categories is via the p_group* fields. And a softer linkage is via a nested "groupOrdering" where you can control the ordering within a category. 

The ordering is any number > 0, and need not be sequential. Lowest numbers position at the top, and higher numbers position further down the page. These numbers may be automatically converted by our system to sequential positions should any item be repositioned within the CMS.  You can use either approach to add and remove products from categories. 

You can use pg_groupid or category_id interchangeably, both are valid. Same for pg_order or category_order. We now supply a read only field category_name for the text of the category. 

If you use the p_groupid* approach, then we will only remove the product from a category if the p_groupid is a negative number. If you do not supply these keys in your update, then no changes will occur.

If you do not provide a complete category ordering array, then we will not remove category linking, unless you specifically add a request parameter, or a json data parameter (in top level) called "DeleteMissingArrayElements".   

Visibility

The p_order field is used to determine general visibility on page and in search.  The field p_order used to determine the position on the page of the product, but that has been deprecated and replaced with each product having a unique position within any category, where a product may belong in multiple categories. The position in categories is now managed in the array "groupOrdering"

• "p_order":1,    (This is a ordinary visible product, the default value)
• "p_order":0,    (This product is hidden from category lists, but remains a searchable product, and you can link to it as you like.)
• "p_order":-1,    (This is a hidden product, and anyone can access if the link is known, but it is excluded from search)
• "p_order":-99,    (This is a hidden/blocked product, and no one can access it)

Security Visibility

The p_minlevelforsee and p_maxlevelforsee fields are focused on a member security level.  Use the min level to require a password. Whereas, use a lower max level, to prevent your wholesale customers viewing the product. The 2 fields together create a range.  Similar fields and rules exist for categories, but products do need to be secured in their own right, as a product can be searched without reference to the multiple categories in which it may reside. 

• "p_minlevelforsee":0     (Anyone can see this product)
• "p_minlevelforsee":100     (Customers must login to see this product)
• "p_minlevelforsee":600     (This product is visible only to POS users)
• "p_minlevelforsee":999     (This is a blocked product, no one can see this)

Promotions / Featured Items

The "p_promote" field is reserved for visual "Stamps" that appear on the product list within a category. If you supply a p_promote field it will also be added to the "promotions" json array, with a default position. 

Use the "promotions" array to manage the promotional targets of your product. If you supply a promotion array, then the item will be promoted in all those categories, but no stamp is created.

You can specify any text as the product promotional stamp. Whereas the array is really intended for specified target areas. 

If you provide no promotions array, there will be no changes to the database for promotions. This is the general approach we have where you only need to supply data if you intend a change to happen. 

You can supply a promo_order of < 0 to force a delete of a specific promotion.

If you do provide an array, but do not provide a complete array, then we will still not adjust promotional lists, unless you specifically add a request parameter, or a json data parameter (in top level) called "DeleteMissingArrayElements".  

Stock Counts

Unlimited stock can be set as p_qtyinstock=9999, or any number less indicate how many are available. If you have sold 3 items on backorder, then the stock level is negative -3

Unlimited backorder stock can be set as p_backorder=9999, or any number less indicates how many are on back order.

There are several more fields to help with reports and stock level targeting.

p_qtyinstock is updated whenever items are sold, or when stock movements are specifically saved. This field can be overridden by specified API connections, and also by importing CSV data. We make a best effort to provide a robust stock count, but acknowledge the needs for many merchants to manage this number externally.