MENU

Categories

Endpoint(s)

https://api.website.world/webapps/api/category   

Description

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.

Methods

POST is used to update a single category, or insert a new single category

GET is used to get a single category or get several categories

Parameters

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

Useful use cases

1. Get all categories

Return all products related to your website. Use GET to retrieve the data.

Example URL: https://api.website.world/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)

Updateable Fields

group_name,  group_img, group_desc,  group_img, group_banner_image, group_subtitle,
group_filename group_keywords, group_metadesc, group_metatitle,
group_parent, group_code, 
group_catid, group_age_target, group_madeincountry,
group_order, group_sorting , group_sort_override,
group_html_header, group_html_footer, group_product_information_tab,
group_privacy_mbrgroupid, group_maxlevelforsee, group_minlevelforsee



Example Return JSON

{
"endPoint": "categories",
"resultCount": 1,
"offset": 0,
"data": [
{
"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
}
],
"success": true,
"pageSize": 200
}

Data Dictionery


NameDescriptionValidationData type
groupid (ID) Category Unique ID, aka ID.
System generated serial. 
Read only
Integer
group_parent Sub categories will point to their parent Category ID. Top level categories will have value = 0Fkey to groupid  Integer
group_name Category name and title. As used in category menu, or within page as the primary link text to navigate to a category. required Text
group_subtitle Sub title, optional field (specific use cases)
Text
group_desc Short description, as might be displayed in a list of categories.
Text
group_codeA third party code used for syncing data during import/export,
Text
group_orderThe position of this category in the list, with reference to the parent category.
0 = hidden but searchable,
-1 = hidden,
-99 = blocked
eg -99,-1,0,1,2,3,...   Integer
group_imgPrimary 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. eg /images/ or https://...Text
group_banner_image If the template supports a banner, then this image will replace the page or site banner. eg /images/Text
group_filename SEO Filename, can be root / based for published file, or otherwise /category/ is prepended for dynamic categories eg /blue-suede-shoesText
group_metatitle SEO Meta Title for search engine results
Text
group_metadesc SEO Meta Description for search engine results
Text
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_sorting Overrides the default sorting of a list of products within the category.. Sorting affects the product list. CHRONO, ALPHA etc
Text
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. 0,2,3,4 Integer
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. eg A1, A2, B1, B2, etc Text
p_price_to Where variants exist, this is the highest price.

<=price Decimal
p_shipping Fixed unit cost for domestic shipping on top of any other freight fees. Decimal
p_shipping_int Fixed unit cost for international shipping on top of any other freight fees  Decimal
group_madeincountry
Country Code of origin. (2 digit country code, one code only. Used with market places.. Cascades to productsNZ,AU,US,CA,CM,JP etcText
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.0,1,2,3,5,10,15,25,50,70Integer
group_catid
Our market places integration will use this generic category ID to associate your products with relevant generic classificationsFKey to third party listInteger
group_minlevelforsee
If only trade customers should see this product, then the value is > 0. If 0, then this product is visible to public.0,100,200,...,999Integer
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. 175,200,300,500,999Integer
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. Fkey reference to mbr_groupidInteger
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. t,fBoolean
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.FKey to groupidInteger
group_cnt_products
Internal count of products in this category (directly connected)Read onlyInteger
group_cnt_products_public
Internal count of products in this category that are visible to general public for market place usageRead onlyInteger
group_cnt_sub_categories
Internal count of sub categories Read onlyInteger
group_html_header
HTML Content displayed at the top of a category (before product list)HTMLText (HTML)
group_html_footer
HTML Content displayed at the end of a category (after product list)HTMLText (HTML)
group_duplicationid
Internal system ID, used when duplicating pages/sites, to identify the original groupid, but becomes unused thereafter.
Integer
group_error_msg
When importing images from third party servers, any error message will be saved here. Basically unused for anything else.
Text
group_pricea_rate (a-h), 
group_price_checkout_rate,
group_price_rrp_rate
Custom adjustment rates, used on some configurations to automatically set prices of products. Exact usage is configuration specific, and consultancy fees apply if you need help with this.0Decimal.
group_product_information_tab
Set content at a category level, that will automatically display on all product information tabs.HTMLText (HTML)
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.ALL = All products
NEW = New products 
NEW180 = New products 180 days
ONSPECIAL = All discounted products 
REVIEWS = All products  with recent reviews.
Text
group_img_size
The size in bytes of the file pointed to by group_img
Integer