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 |
| cid |
cid
System ID representing the website ID
|
int
|
Max Len: 11
|
| group_catid |
group catid
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
|
Max Len: 11
|
| group_duplicationid |
group duplicationid
Internal system ID, used when duplicating pages/sites, to identify the original groupid, but becomes unused thereafter.
|
int
|
Max Len: 11
|
| group_parent |
group parent
Sub categories will point to their parent Category ID. Top level categories will have value = 0 (Validation: Fkey to groupid )
|
int
|
Max Len: 11
|
| group_privacy_mbrgroupid |
group privacy mbrgroupid
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
|
Max Len: 11
|
| page |
page
System ID representing the page ID
|
int
|
Max Len: 11
|
| group_age_target |
group 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
|
Max Len: 11
|
| group_all_products |
group all products
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 products
NEW = New products
NEW180 = New products 180 days
ONSPECIAL = All discounted products
REVIEWS = All products with recent reviews.)
|
text
|
|
| group_banner_image |
group banner image
If the template supports a banner, then this image will replace the page or site banner. (Validation: eg /images/)
|
text
|
|
| group_cnt_products |
group cnt products
Internal count of products in this category (directly connected) (Validation: Read only)
|
int
|
Max Len: 11
|
| group_cnt_products_public |
group cnt products public
Internal count of products in this category that are visible to general public for market place usage (Validation: Read only)
|
int
|
Max Len: 11
|
| group_cnt_sub_categories |
group cnt sub categories
Internal count of sub categories (Validation: Read only)
|
int
|
Max Len: 11
|
| group_code |
group code
A third party code used for syncing data during import/export,
|
text
|
|
| group_desc |
group desc
Short description, as might be displayed in a list of categories.
|
text
|
|
| group_error_msg |
group error msg
When importing images from third party servers, any error message will be saved here. Basically unused for anything else.
|
text
|
|
| group_filename |
group 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_html_footer |
group html footer
HTML Content displayed at the end of a category (after product list) (Validation: HTML)
|
text
|
|
| group_html_header |
group html header
HTML Content displayed at the top of a category (before product list) (Validation: HTML)
|
text
|
|
| group_img |
group img
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_keywords |
group 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 |
group linkgroupid
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
|
Max Len: 11
|
| group_madeincountry |
group madeincountry
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 |
group maxlevelforsee
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
|
Max Len: 11
|
| group_metadesc |
group metadesc
SEO Meta Description for search engine results
|
text
|
|
| group_metatitle |
group metatitle
SEO Meta Title for search engine results
|
text
|
|
| group_minlevelforsee |
group minlevelforsee
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
|
Max Len: 11
|
| group_name |
group 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_order |
group 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
|
Max Len: 11
|
| group_privacy_cascade |
group privacy cascade
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
|
Max Len: 1
true/false
|
| group_product_information_tab |
group product information tab
Set content at a category level, that will automatically display on all product information tabs. (Validation: HTML)
|
text
|
|
| group_search_advanced |
group search advanced
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
|
Max Len: 11
|
| group_sorting |
group sorting
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 |
group 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 |
group subtitle
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
API End Points
Content
Blog pages are usually presented as a list udner a primary page. Individual blog pages do not appear on the menu, only in lists. The blog engine also powers FAQ and gallery type pages
EndPoint: https://api.cms-tool.net/webapps/api/blog
A website is made up of the primary navigational pages that create the primary menu, as well as hidden pages and member only pages. Pages can contain pages in a treelike structure, however, this excludes sub pages which are defined as blogs or products
EndPoint: https://api.cms-tool.net/webapps/api/page
Ecommerce
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.
EndPoint: https://api.cms-tool.net/webapps/api/category
Each product line of an order can be discounted, so an order can have multiple discounts, but only one per product.
EndPoint: https://api.cms-tool.net/webapps/api/discount
The available payment methods at checkout. An order can only have 1 payment method, but the admin can change the payment method, and take part payments.
EndPoint: https://api.cms-tool.net/webapps/api/paymentop
A saleable item, or variant of a parent product.
EndPoint: https://api.cms-tool.net/webapps/api/product
Invoices, orders, baskets and quotes are all represented by this object, and differentiated by status.
EndPoint: https://api.cms-tool.net/webapps/api/basket
The courier or freight fee rules available for checkout. Each order can only have rule applied
EndPoint: https://api.cms-tool.net/webapps/api/shipping
Members
Bulk emails represent a newsletter that will be sent to a bulk audience via a mailing list. Alternatively, a bulk email is a sequence within a campaign.
EndPoint: https://api.cms-tool.net/webapps/api/bulkemail
A message is created for every contact us, enquiry form, or custom form.
EndPoint: https://api.cms-tool.net/webapps/api/message
Group members/customers, each member can belong to unlimited groups. Groups can contain groups
EndPoint: https://api.cms-tool.net/webapps/api/membergroups
System security levels. Default level is 100 for general users.
EndPoint: https://api.cms-tool.net/webapps/api/reference/memberlevel
Members or customers or users are the same thing. These are anyone who has purchased, enquired, or who has permission to login, or receive newsletters. This excludes administrative users.
EndPoint: https://api.cms-tool.net/webapps/api/member
A blog comment or product review uses the same engine. Each record may have a rating, as well as an optional comment, and is linked to an object and the person who posted it
EndPoint: https://api.cms-tool.net/webapps/api/comments
Other
Bookings are for appointments, seats, hire items, etc. Not for events.
EndPoint: https://api.cms-tool.net/webapps/api/booking
Use the Event Attendee endpoint to get your event attendee information on your site.
EndPoint: https://api.cms-tool.net/webapps/api/eventAttendee
Events have a start/end date and additional information, they might be bookable, or just for informational purposes
EndPoint: https://api.cms-tool.net/webapps/api/event
Reference
A list of countries, and some meta data
EndPoint: https://api.cms-tool.net/webapps/api/reference/countries
EndPoint: https://api.cms-tool.net/webapps/api/reference/currencies
EndPoint: https://api.cms-tool.net/webapps/api/reference/fx
Generic categories are those that relate to open source categorisations of products for SEO purposes
EndPoint: https://api.cms-tool.net/webapps/api/reference/categories
EndPoint: https://api.cms-tool.net/webapps/api/reference/postcodes