MenuClose
CONTENT MANAGEMENT SYSTEM ONLINE HELP
Categories - API Reference
Categories
Categories are used to group products. Products can belong in up to 8 categories. Categories can also form a tree, with Category parent ID = 0 being the parent level category. The term group is synomous with category, so many elements are prefixed with the word group.
End Point URL
https://api.cms-tool.net/webapps/api/category
API Parameters and Filters
| Name | Description | Example | Optional | Data type |
| data | The JSON you would like to POST. This can be POST content also | data = {"id":2334453,"group_name":"Books"} | Yes | json object |
| id | Fetch a specific cateory | id=2334453 | Yes | int |
| page | Only categories for a specific page | page=435 | int | |
| keywords |
Filter results based on keywords: Site search keywords |
keywords=abc |
Yes | string |
| code |
Filter results based on group_code: Product code |
group_code=123 | Yes | string |
| parentid |
Filter results based on Parent Category id (0 if parent level) |
parentid=123 or group_parent=123 |
Yes | int |
| name |
Filter results based on Category name/title |
name=books or group_name=books | Yes | string |
| filename |
Filter by group filename |
filename=/cookbooks.html | Yes | string |
Data Dictionary
| Key | Definition | Type | Format |
| groupid |
ID
Primary ID for the category / group of products
|
Integer (Unique ID)
|
e.g. 123456
|
| cid |
Website ID
System ID representing the website ID
|
int
|
e.g. 123456
|
| group_catid |
Generic Category ID
Our market places integration will use this generic category ID to associate your products with relevant generic classifications (Validation: FKey to third party list)
|
int
|
|
| group_duplicationid |
Duplication ID
Internal system ID, used when duplicating pages/sites, to identify the original groupid, but becomes unused thereafter.
|
int
|
|
| group_parent |
Parent Category ID
Sub categories will point to their parent Category ID. Top level categories will have value = 0 (Validation: Fkey to groupid )
|
int
|
|
| group_privacy_mbrgroupid |
Security - Member Group ID
If only selected user groups should see this, then a non zero ID of the required member group. Usually this should be used in conjunction with a group_minlevelforsee>0 for best security. (Validation: Fkey reference to mbr_groupid)
|
int
|
|
| page |
Page ID
System ID representing the page ID
|
int
|
e.g. 123456
|
| group_age_target |
Age Target
Target age of product user. Only the following integers are used, indicating the closest target age group. eg 25 young adult. 50 mature adult. 70 retired. If value is > 0 then cascades to products automatically. Used with market places. (Validation: 0,1,2,3,5,10,15,25,50,70)
|
int
|
|
| group_all_products |
All Product Filter Mode
Not your ordinary category, this category will ignore any products assigned to it, but will instead search all products in your database that match some special rules. (Validation: ALL = All productsNEW = New products NEW180 = New products 180 daysONSPECIAL = All discounted products REVIEWS = All products with recent reviews.)
|
text
|
|
| group_all_products_filter |
All products filter text
When using the All Product Filter Mode, this field might provide additional filter keywords to apply, eg a brand name to match on if all product filte rmode is brand.
|
text
|
|
| group_api_auto_add |
API sync auto add
Should products be automatically added to this category?
|
bool
|
true/false |
| group_api_auto_last_lookup |
API sync auto last lookup
The timestamp of the last sync of this category
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| group_api_extra_params |
API sync extra params
Extra parameters required to sync this category with a third party category
|
text
|
|
| group_api_setting_id |
API sync setting id
Which API connection is active as the master/source for syncing products with this category
|
int
|
|
| group_api_source |
API Source Name
Depricated - A textual name to quickly identify which API name linked to this category
|
text
|
|
| group_api_source_id |
API source id
GUID or similar third party category ID that is linked to our category
|
text
|
|
| group_api_source_name |
API source name
The name of the third party category that is synced with this category
|
text
|
|
| group_banner_image |
Image Banner Src
If the template supports a banner, then this image will replace the page or site banner. (Validation: eg /images/)
|
text
|
|
| group_banner_img_json |
Image Banner Meta
Additional meta data about the banner image, eg size and resolution
|
json
|
|
| group_cnt_products |
Count products
Internal count of products in this category (directly connected) (Validation: Read only)
|
int
|
|
| group_cnt_products_public |
Count products public
Internal count of products in this category that are visible to general public for market place usage (Validation: Read only)
|
int
|
|
| group_cnt_sub_categories |
Count sub categories
Internal count of sub categories (Validation: Read only)
|
int
|
|
| group_code |
Code
A third party code used for syncing data during import/export,
|
text
|
|
| group_data_json |
Additional Data
Additional Data about this category
|
json
|
|
| group_desc |
Description
Short description, as might be displayed in a list of categories.
|
text
|
|
| group_filename |
SEO Filename
SEO Filename, can be root / based for published file, or otherwise /category/ is prepended for dynamic categories (Validation: eg /blue-suede-shoes)
|
text
|
|
| group_google_category |
Google Category Code
eg as per https://support.google.com/merchants/answer/6324436?hl=en
|
text
|
|
| group_html_footer |
HTML Footer
HTML Content displayed at the end of a category (after product list) (Validation: HTML)
|
text
|
|
| group_html_header |
HTML Header
HTML Content displayed at the top of a category (before product list) (Validation: HTML)
|
text
|
|
| group_img |
Image Source
Primary image for a category as displayed in a list of categories. When importing data, you can reference an external URL to an image, and some minutes/hours later, the image file will be migrated to our server, and the database updated to use a local reference. (Validation: eg /images/ or https://...)
|
text
|
|
| group_img_json |
Image Meta Data
Meta data about the primary image for the category
|
json
|
|
| group_keywords |
SEO Meta keywords
SEO Meta Keywords for search engine tuning. Also used for internal searches. Google suggests this should only contain words that are visible in your content.
|
text
|
|
| group_linkgroupid |
Link Group ID
Dummy link to a target category. Essentially this category doesn't exist, but simply links to the target category, and the target category name/description/url etc takes precedence for display. (Validation: FKey to groupid)
|
int
|
|
| group_madeincountry |
Country Of Origin
Country Code of origin. (2 digit country code, one code only. Used with market places.. Cascades to products (Validation: NZ,AU,US,CA,CM,JP etc)
|
text
|
|
| group_maxlevelforsee |
Security - Maximum User Level
If no trade customners should see this product, then the value should be 175, that includes a broad range of retail customer levels. 200 level is an authorised user. (Validation: 175,200,300,500,999)
|
int
|
|
| group_metadesc |
SEO Meta Description
SEO Meta Description for search engine results
|
text
|
|
| group_metatitle |
SEO Meta Title
SEO Meta Title for search engine results
|
text
|
|
| group_minlevelforsee |
Security - Minimum User Level
If only trade customers should see this product, then the value is > 0. If 0, then this product is visible to public. (Validation: 0,100,200,...,999)
|
int
|
|
| group_name |
Category Name
Category name and title. As used in category menu, or within page as the primary link text to navigate to a category. (Validation: required)
|
text
|
|
| group_old_category_parent |
Import Parent Name
Used during imports only...provides the parent category name, ID,. or parent code, and then converts to an ID
|
text
|
|
| group_order |
Sort Order
The position of this category in the list, with reference to the parent category. 0 = hidden but searchable,-1 = hidden, -99 = blocked (Validation: eg -99,-1,0,1,2,3,... )
|
int
|
|
| group_pricea_rate |
Auto price matrix - Price A
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_priceb_rate |
Auto price matrix - Price B
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_price_checkout_rate |
Auto price matrix - Price Default
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 12.2
|
| group_pricec_rate |
Auto price matrix - Price C
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_priced_rate |
Auto price matrix - Price D
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_pricee_rate |
Auto price matrix - Price E
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_pricef_rate |
Auto price matrix - Price F
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_priceg_rate |
Auto price matrix - Price G
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_priceh_rate |
Auto price matrix - Price H
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 10.2
|
| group_price_rrp_rate |
Auto price matrix - Price RRP
Only when prices of products in this category should use the rate card from a base price
|
text
|
Precision: 12.2
|
| group_privacy_cascade |
Security - Cascading
Optional setting to apply the above privacy rules to all products within this category. By default, products are soft linked to categories, and category privacy does not impact on products. (Validation: t,f)
|
bool
|
true/false |
| group_product_information_tab |
HTML Information Tab
Set content at a category level, that will automatically display on all product information tabs. (Validation: HTML)
|
text
|
|
| group_search_advanced |
Category Split
The category menus can be split into multiple menus, so 2 = secondary menu, 3 = third menu etc. Primarily this is used with the template advanced product search filter widget. (Validation: 0,2,3,4)
|
int
|
|
| group_sorting |
Product List Sorting Mode
Overrides the default sorting of a list of products within the category.. Sorting affects the product list. (Validation: CHRONO, ALPHA etc)
|
text
|
|
| group_sort_override |
Category Sort Override
Irrespective of how categories are usually sorted within a list of categories, this sort override will take preference. Allowing you to have a finer control over over the sorting. Sorting by this column is alphanumeric. Default sorting will take second precedence if this column is blank. Advanced users only. (Validation: eg A1, A2, B1, B2, etc)
|
text
|
|
| group_subtitle |
Sub Title
Sub title, optional field (specific use cases)
|
text
|
Usage Instructions and Examples
1. Get all categories
Return all products related to your website. Use GET to retrieve the data.
Example URL: https://api.cms-tool.net/webapps/api/categories
Replace the apiID and apiKey with your website credentials
2. Update an existing category
To update an existing category you must include the category id and the fields you would like to update in the data JSON value.
Example: data =
{
"id": 12345,
"group_name": "Updated category",
"group_desc": "Updated description for category"
}
3. Create a new category
To create a new category do not include the category id. Just define the fields in the data JSON value.
{
"group_name": "New category",
"group_desc": "New description for category"
}
Sorting / Ordering / Visibility
"group_order":1, (Order 1,2,3,4.... anything over 0 is visible and the primary sorting value.)
"group_order":0, (This category is hidden from lists, but remains searchable, and you can link to it as you like.)
"group_order":-1, (This is a hidden category, and anyone can access if the link is known, but it is excluded from search)
"group_order":-99, (This is a hidden/blocked category, and no one can access it)
The above visibility rules only affect categories, and not the products within them. Products can have their own visibility rules, as products can be linked to multiple categories, or exist independently of all categories.
There are also some security visibility fields
group_minlevelforsee = 0-999 (Level ID of the minimum member level who can view this, usually 0 for public access, but if you want only logged in users to see this category, then incrdease this number)
group_maxlevelforsee = 0-999 (Level ID of the maximum member level who can view this, usually 999 but if you want only retail users to see this category, then reduce this number)
group_privacy_mbrgroupid (Integer ID of the member group, or 0 if no security rule)
Sample Object
{"group_privacy_mbrgroupid":0,}
"group_pricea_rate":"0.00",
"group_linkgroupid":-9,
"group_pricee_rate":"0.00",
"group_duplicationid":0,
"group_priceh_rate":"0.00",
"group_priceb_rate":"0.00",
"group_search_advanced":0,
"id":198902,
"group_parent":0,
"group_name":"API Products",
"groupid":123,
"group_pricef_rate":"0.00",
"group_minlevelforsee":0,
"group_cnt_sub_categories":0,
"group_cnt_products":0,
"group_cnt_products_public":0,
"group_pricec_rate":"0.00",
"group_catid":0,
"group_hidden":" ",
"page":0,
"group_order":100,
"group_priced_rate":"0.00",
"group_priceg_rate":"0.00",
"cid":111