Categories API v2
The Category resource lets you get, create, update or remove categories from an Account's product catalogue.
Product Categories (sometimes known as collections) organise products into a hierarchical catalogue.
Scopes
Access to the Categories API requires that the client have the following scopes granted:
products- Permits write access to add, update or remove categories.products.readonly- Read only access to search or get category data.
The Category object
alias
required
The unique URL path to the Category page. The alias property must start with its parent's alias (with the exception of
the root category). Changing a category's alias affects the alias of all its descendants.
|
createdOn
The datetime in ISO-8601 format when the Category was created (e.g. 2024-07-09T17:53:55+01:00). |
createdBy
An integer representing the Contact ID who created the Category. This may be set to null if
the Category was created by an App or via import.
|
description
The short description for a Category may have up to 255 characters (may not contain HTML). |
enableFilters
A boolean value determining whether a Category should show/use filters, if configured.
|
id
read-only
An unsigned 64-bit integer, which is unique across all Categories and all Evance Accounts. |
image
Typically used as a secondary/alternate image to the thumbnail (below) or as a banner image on the Category page. The URL to an image in the Media Library may be a
Evance requires images to be imported into the Media Library. If you supply the image as a Data URI, or an external URL, Evance will import the image into the Media Library. |
inheritLocales
A boolean value determining whether a Category should inherit locale visibility from its closest configured ancestor or the root.
|
isActive
A boolean value determining whether a Category is enabled or disabled:
A Category’s |
isFeatured
A boolean value determining whether a Category should be featured:
The implementation of featured categories may vary between Themes. Typically, featured categories are flagged to appear on a website's homepage. Some Themes may display featured categories differently. |
isIndexable
A boolean value determining whether a Category should be indexed by external search engines:
When a Category is not indexable Evance will add a |
isSearchable
A boolean value indicating whether the Category can be found using the website's search facility.
|
left
read-only
The left nested position of the category. |
metaDescription
String up to 255 characters used for the Category’s SEO meta description ( <meta name="description">)
- may not contain HTML.
When a Category’s metaDescription is empty, its short description will be used.
|
metaKeywords
A string containing comma-separated SEO-friendly keywords to be included in the Category’s <meta name="keywords"> tag.
These keywords are also relevant to the on-site search facilities. |
metaTitle
A string up to 120 characters containing the Product's SEO-friendly page title. When a Category’s metaTitle is empty, its title will be used.
|
modifiedOn
The datetime the Category was last modified in ISO-8601 format (e.g. 2024-07-09T17:53:55+01:00) |
modifiedBy
An integer representing the Contact ID of the last user to modify the Category. |
parentId
read-only
An unsigned 64-bit integer - the ID of the parent Category. Evance permits one root Category per Tenant, therefore the only Category with a null value for parentId will
be the Tenant’s default/entry category.
|
productOrder
Allows you to define the default sort order of products shown on the Category page, which may be one of the
following:
Defaults to |
publishStartOn
Accepts a date in ISO-8601 format (e.g. Defaults to |
publishEndOn
Accepts a date in ISO-8601 format (e.g. Defaults to |
right
read-only
The right nested position of the category. |
status
read-only
There are only two statuses for a Category:
A Category’s
|
template
A string representing the Category Template reference defined in the Templates Config. This affords merchants the flexibility to display some Categories differently to others. However, most sites only have a default (“index”) Category template. When set to null the default template is assumed.
Defaults to null.
|
thumbnail
The URL to an image in the Media Library may be a
Evance requires images to be imported into the Media Library. If you supply the image as a Data URI, or an external URL, Evance will import the image into the Media Library. The thumbnail represents the category when displayed on a parent Category page and sharing on social media. |
title
required
A string up to 120 characters. |
Positioning a category
The position of a category is represented by its parentId,
leftand right properties. Each of these properties are read-only.
When adding or moving a category you may define where the category appears in the hierarchy by including a position object.
The object must contain the following properties:
{
"position": {
"placement": "first",
"id": 1234
}
}
This object may be supplied to the POST and PUT endpoint to move an
existing category or insert a category at the desired position. The only category which may not accept a position object
is the root category, which is denoted by a category with a parentId of
null.
You should be aware that moving a category to a different parent will affect its alias and the alias of all of its descendants. However, their original URLs will be remembered and 301 redirects established to prevent traffic loss.
The position object is for modification only and is
NOT included in GET requests.
List/search categories
GET
/api/v2/categories.json
Get or search for one or more categories using a range of accepted query parameters.
Product categories are hierarchical, however this resource returns category data in a flat format. This allows developers to retrieve category data based on nested set positions:
- To find children of a Category supply its ID to the
parentIdorparentId:inparameter. - To find all descendants of a Category you can supply its left and right position to
left:afterandright:beforerespectively. - To find all ancestors of a Category (it parents) you can supply its left and right position to
left:beforeandright:afterrespectively.
Query parameters
createdOn:min
Return categories with a createdOn datetime greater than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
createdOn:max
Return categories with a createdOn datetime less than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
createdOn:after
Return categories with a createdOn datetime greater than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
createdOn:before
Return categories with a createdOn datetime less than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
|
id:in
Return categories specified within a comma-separated list of Category IDs. |
left:min
Return categories with a left position greater than or equal to the value supplied. |
left:max
Return categories with left position less than or equal to the value supplied. |
left:after
Return categories with a left position greater than the value supplied. |
left:before
Return categories with a left position less than the value supplied. |
modifiedOn:min
Return categories with a modifiedOn datetime greater than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
modifiedOn:max
Return categories with a modifiedOn datetime less than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
modifiedOn:after
Return categories with a modifiedOn datetime greater than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
modifiedOn:before
Return categories with a modifiedOn datetime less than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
|
parentId
Return child categories of a single Category ID. |
parentId:in
Return child categories of one or more Category IDs. |
right:min
Return categories with a right position greater than or equal to the value supplied. |
right:max
Return categories with right position less than or equal to the value supplied. |
right:after
Return categories with a right position greater than the value supplied. |
right:before
Return categories with a right position less than the value supplied. |
status
Return categories matching the supplied status:
public status when it meets the following criteria:
|
JSON response
Evance will return a JSON object containing the following properties:
success
A successful search request containing zero or more results will always return a true value.
|
status
An integer matching the HTTP response code. A successful request will have a status of 200.
|
data
An array containing zero or more Category data objects. |
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
|
links
An object containing links to traverse available search results.
|
Example JSON response
{
"success": true,
"status": 200,
"data": [
{
"id": 1234,
"parentId": 1233,
"template": null,
"title": "Drinks",
"alias": "/products/drinks",
"description": "This is a short description",
"metaTitle": "Browser SEO title",
"metaDescription": "SEO friendly description",
"metaKeywords": "CSV of relevant keywords",
"thumbnail": "/portal/web/gateway/content/url",
"image": "/portal/web/gateway/content/url",
"status": "public",
"isActive": true,
"isFeatured": false,
"isSearchable": true,
"isIndexable": true,
"enableFilters": false,
"inheritLocales": false,
"publishStartOn": null,
"publishEndOn": null,
"productOrder": "price:asc",
"left": 2,
"right": 3,
"createdOn": "2024-07-09T14:50:02+00:00",
"createdBy": 1,
"modifiedOn": "2024-07-09T14:50:02+00:00",
"modifiedBy": 1
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/categories.json",
"previous": null,
"next": null
}
}
Get a single Category
GET
/api/v2/categories/{id}.json
Retrieve a single Category using its ID.
URL parameters
id
required
The ID of the Category is supplied as a path parameter. |
Response
Returns an object with the following properties:
success
A boolean where a value of true represents a successful request.
|
status
The HTTP status code e.g. 200 for a successful request.
|
data
Contains the Category object. |
Example JSON response
{
"success": true,
"status": 200,
"data": {
"id": 1234,
"parentId": 1233,
"template": null,
"title": "Drinks",
"alias": "/products/drinks",
"description": "This is a short description",
"metaTitle": "Browser SEO title",
"metaDescription": "SEO friendly description",
"metaKeywords": "CSV of relevant keywords",
"thumbnail": "/portal/web/gateway/content/url",
"image": "/portal/web/gateway/content/url",
"status": "public",
"isActive": true,
"isFeatured": false,
"isSearchable": true,
"isIndexable": true,
"enableFilters": false,
"inheritLocales": false,
"publishStartOn": null,
"publishEndOn": null,
"productOrder": "price:asc",
"left": 2,
"right": 3,
"createdOn": "2024-07-09T14:50:02+00:00",
"createdBy": 1,
"modifiedOn": "2024-07-09T14:50:02+00:00",
"modifiedBy": 1
}
}
Add a new Category
POST
/api/v2/categories.json
Add a Category to your product catalogue.
Requires the products OAuth scope.
Request body
Your request body must contain an object including:
data
required
Containing a Category object. |
Example JSON request
The minimum requirements for a Category is a title. However, to avoid URL conflicts you should
supply a unique alias.
Since categories are hierarchical, a category without a position object will be inserted
as the last child of the website's root category.
{
"data": {
"title": "Drinks",
"alias": "/products/drinks",
"description": "Make mine a double"
}
}
Success response
If the Category was created successfully you should receive a response with a 201 status
code:
success
A boolean where a value of true means the Category was created successfully.
|
status
The HTTP status code e.g. 201 means the Category was created successfully. |
data
Contains the Category object you created including its new id. |
Error responses
If the Category could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the Category could not be created.
|
status
A response code of 422 means the Category could not be created and you should
check the errors property for further information. |
context
The context property indicates where the error occurred. For a 422 error this
will typically contain a value of data, indicating that there was an error
with the data object supplied. |
errors
Contains an array of error objects, each will have the following properties:
|
Update a Category
PUT
/api/v2/categories/{id}.json
Update a Category already within your product catalogue by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Category object |
Request body
Your request body must contain an object including:
data
required
Containing updates to your Category object. |
Example JSON request
To update a Category you must PUT JSON to this resource within a data object. You do
not need to supply all properties and may choose to only supply properties that require modifying.
{
"data": {
"title": "Drinks",
"alias": "/products/drinks",
"description": "That's the spirit"
}
}
Success response
If the Category was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the Category was updated successfully.
|
status
The HTTP status code e.g. 200 means the Category was updated successfully. |
data
Contains the Category object you updated inlcuding any adjustments. |
Error responses
If the Category could not be updated you will encounter a response with either a 400,
404or
422status code:
success
A boolean where a value of false means the Category could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
Delete a Category
DELETE
/api/v2/categories/{id}.json
Delete a Category (sometimes known as a collection) within your product catalogue by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Category object |
Request body
Does not require a payload
Success response
If the Category was deleted successfully you should receive a response with a 204 status
code and no body. Categories are hierarchical, any sub-categories will also be deleted.
Error responses
If the Category could not be deleted you may encounter a response with a 400, or 404 status
code:
success
A boolean where a value of false means the Category could not be deleted.
|
status
|