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.

  • true - show filtering if configured.
  • false (default) - hide filters even 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 JPEG, GIF, or PNG file up to 20MB in size.

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.

  • true (default) - use an ancestor’s locale visibility settings.
  • false the category uses its own locale visibility settings.
isActive

A boolean value determining whether a Category is enabled or disabled:

  • true - enabled.
  • false - disabled.

A Category’s isActive status contributes to the overall visibility status.

isFeatured

A boolean value determining whether a Category should be featured:

  • true - featured.
  • false (default) - not 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:

  • true - (default) - allow search engines to index the page
  • false the category should not be indexed by external search engines like Google.

When a Category is not indexable Evance will add a <meta name="robots" content="noindex" /> meta tag to the Category page. However, the Category will remain available to the Website's internal search engine (see isSearchable).

isSearchable

A boolean value indicating whether the Category can be found using the website's search facility.

  • true (default) - the Category is included in search results.
  • false - the Category is excluded from search results.
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:

  • price:asc - Price low to high
  • price:desc - Price high to low
  • sequence:asc - Custom sequence defined by the merchant
  • created:desc - Newest to oldest
  • created:asc - Oldest to newest
  • title:asc - Product title A-Z
  • title:desc - Product title Z-A
  • sku:asc - SKU A-Z
  • sku:desc - SKU Z-A

Defaults to pricing:desc.

publishStartOn

Accepts a date in ISO-8601 format (e.g. 2022-01-01) or null. This setting allows merchants to populate their catalogue and schedule category releases in advance. If a null value is supplied the Category is assumed to have an immediate start date.

Defaults to null.

publishEndOn

Accepts a date in ISO-8601 format (e.g. 2022-01-01) or null. This setting allows merchants to schedule when categories are no longer available - removing them from the website. If a nullvalue is supplied the Category will not expire.

Defaults to null.

right read-only
The right nested position of the category.
status read-only

There are only two statuses for a Category:

  • admin (default) - only accessible by administrators.
  • public - available to all.

A Category’s status is calculated and considered public if all statements below are true:

  • All of the Category’s ancestors have a public status.
  • The Category is active/enabled (see isActive)
  • Has no publish date, or a past publish date (see publishStartOn)
  • Has no expiry date, or an expiry date in the future (see publishEndOn)
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 JPEG, GIF, or PNG file up to 20MB in size.

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:

placement required

May be one of the following:

  • first - insert or move the category as the first child of the id(below).
  • last - insert or move the category as the last child of the id (below).
  • before - insert or move the category before a sibling with id (below)
  • after - insert or move the category after a sibling with id (below)

id required

When the placement is before or after, the value of id should be that of a sibling category, which acts as a reference point.

When the placement is first or last, the value of id should be that of the parent category.

 

{
  "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 parentId or parentId:in parameter.
  • To find all descendants of a Category you can supply its left and right position to left:after and right:beforerespectively.
  • To find all ancestors of a Category (it parents) you can supply its left and right position to left:before and right:after respectively. 

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:
  • admin - categories only visible to site administrators.
  • public - categories that are available for display to the public.
A category has a public status when it meets the following criteria:
  • The category is marked as active (isActive=true)
  • The category is published with a publishStartDate of null or with a date less than or equal to the current date.
  • The category is published with a publishEndDate of null or with a date in the future.


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.
  • limit - the number of categories to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or nullif there isn't one.
  • next - a URL for the next results page, or null if there isn't one

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:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).


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
  • 400 may indicate that the ID was not provided.
  • 404 means Category could not be found by the ID provided.
  • 422 means the Category could not be updated due to errors in the data supplied.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the Category data supplied.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).


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
  • 400 may indicate that the ID was not provided, or the Category could not be deleted for an unknown reason.
  • 404 indicates that the ID was provided, but the Category could not be found.