Category

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

The Category Service allows you to manage your store's categories and resources assigned to them.

Note: When X-Version header is required use v2, otherwise the header is not necessary.

Assignment Resources

Manage Assignments

Retrieving a list of categories for which the reference id is assigned

Retrieves a list of categories for which the reference id is assigned.

Required scopes

  • category.category_read_unpublished

    Note: Only required if the category has not been published.

SecurityOAuth2
Request
path Parameters
tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
referenceId
required
string

Assignment's reference unique identifier, for example: productId.

Example: 44170435
query Parameters
showUnpublished
boolean
Default: false

If set to true, resources assigned to not published categories are retrieved as well. Possible values:

  • true
  • false Note: To get unpublished categories you need to have category.category_read_unpublished scope.
Example: showUnpublished=true
expandSupercategoriesIds
boolean
Default: false

If set to true, each entry is enriched with supercategoriesIds field containing supercategories ids. Possible values:

  • true
  • false
Example: expandSupercategoriesIds=true
pageNumber
integer <int32> >= 1
Default: 1

Page number to be retrieved. The number of the first page is 1. Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

pageSize
integer <int32> >= 1
Default: 60

Number of export files to be retrieved per page.

sort
string

List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden. Possible values:

  • {fieldName}:ASC
  • {fieldName}:DESC
  • {fieldName}:ASC,{fieldName2}:DESC
  • {internationalizedFieldName.en}:ASC - contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.
  • {internationalizedFieldName}:ASC - contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
Example: sort={fieldName}:ASC,{fieldName2}:DESC
header Parameters
Accept-Language
string
Default: *

List of properties used to project and sort the results, separated by commas. Possible values:

  • * - each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.
  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$

To use this endpoint you have to add X-Version header with proper value to your request.

Note: The header value has to match following regular expression: ^v[1-9][0-9]?$

Example: v2
X-Total-Count
boolean
Default: false

The header value indicates if the total count of entities should be returned. Possible values:

  • true
  • false Default value: false
Example: true
Responses
200

The request was successful. The categories for given reference id are returned.

400

Request was syntactically incorrect. Details will be provided in the response payload

403

Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.

404

Reference with the specified reference id does not exist

get/{tenant}/assignments/references/{referenceId}
Request samples 
Response samples 
application/json
[
  • {
    }
]
Deleting all assignments by referenceId
Deletes all assignments for a specified referenceId, e.g. all assignments for a given productId.




Required scopes


    

  • category.category_update
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
referenceId
required
string
Assignment's reference unique identifier, for example: productId.


 
 Example:  1256792345
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
204
Assignments has been successfully deleted


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Assignment with given referenceId does not exist


delete/{tenant}/assignments/references/{referenceId}
Request samples 
Response samples 
application/json
{ }
Category Resources
Manage Categories


Retrieving a list of categories
Retrieves a list of categories for a given tenant.




Required scopes


    

  • category.category_read_unpublished
    

    Note: Only required if the response should contain unpublished categories.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
query Parameters
showRoots
boolean
 Default:  false
If set to true, only root categories (categories without parents) are retrieved.
Possible values:


    

  • true
    • 

  • false
    • 



 
 Example:  showRoots=true
showUnpublished
boolean
 Default:  false
If set to true, not published categories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
Note: To get unpublished categories you need to have category.category_read_unpublished scope.
    • 



 
 Example:  showUnpublished=true
pageNumber
integer <int32>   >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer <int32>   >= 1 
 Default:  60
Number of export files to be retrieved per page.


 
sort
string
List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden.
Possible values:


    

  • {fieldName}:ASC
    • 

  • {fieldName}:DESC
    • 

  • {fieldName}:ASC,{fieldName2}:DESC
    • 

  • {internationalizedFieldName.en}:ASC - contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.
    • 

  • {internationalizedFieldName}:ASC - contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
    • 



 
 Example:  sort={fieldName}:ASC,{fieldName2}:DESC
code
string
Search by the code value. The equal case insensitive operator is used for this parameter therefore the provided value must exactly match the stored value.


 
 Example:  code=3A001
localizedName
string
Search by the localizedName of the categories, it will be conformed against all of the specified accepted-languages.


 
 Example:  localizedName=Example category name
localizedDescription
string
Search by the localizeDescription of the categories, it will be conformed against all of the specified accepted-languages.


 
 Example:  localizedDescription=Example category description
localizedSlug
string
Search by the localizedSlug of the categories, it will be conformed against all of the specified accepted-languages.


 
 Example:  localizedSlug=Example category slug
ecn
string
Search by the ECN value. The equal operator is used for this parameter therefore the provided value must exactly match the stored value.


 
 Example:  ecn=3A001
validityFrom
string
Search by categories with 'validity.from' date field which is after specified value. It must follow the pattern: 'yyyy-MM-dd'.


 
 Example:  validityFrom=2022-11-01
validityTo
string
Search by categories with 'validity.to' date field which is before than specified value. It must follow the pattern: 'yyyy-MM-dd'.


 
 Example:  validityTo=1997-11-01
metadataModifiedAt
string
Search by categories with 'metadata.modifiedAt' date field which is after specified value. It must follow the pattern: 'yyyy-MM-dd'.


 
 Example:  metadataModifiedAt=2022-01-28
header Parameters
Accept-Language
string
 Default:  *
List of properties used to project and sort the results, separated by commas.
Possible values:


    

  • * - each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.
    • 

  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
    • 

  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
X-Total-Count
boolean
 Default:  false
The header value indicates if the total count of entities should be returned.
Possible values:


    

  • true
    • 

  • false
Default value: false
    • 



 
 Example:  true
Responses 
200
The request was successful. The categories are returned.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


get/{tenant}/categories
Request samples 
Response samples 
application/json
[
  • {
    }
]
Creating a new category
Creates a new category.
Creating category as a root may be achieved by adding the 'parentId' field with a 'root' value or by not providing the 'parentId' in the payload.




Required scopes


    

  • category.category_create
    

    • 

  • category.category_publish
    

    Note: The category.category_publish scope is only required if you want to publish the category when creating it.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
query Parameters
publish
boolean
 Default:  false
If set to true category may be published when updated, otherwise may be unpublished. It must match value of 'published' field of the request body.
Possible values:


    

  • true
    • 

  • false
Note: To publish a category you need to have category.category_publish scope.
Note: To unpublish a category you need to have category.category_unpublish scope.
    • 



 
 Example:  publish=true
header Parameters
Content-Language
string
 Default:  *
The Content-Language request HTTP header defines language(s) of the payload. Request body may contain only translations that are matching the languages specified in the header.
Possible values:


    

  • * - request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.
    • 

  • en, en,de, fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - request body may contain only translations for languages specified in the header (if they are available in tenant configuration) .
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Request Body schema: application/json
required
object  non-empty 
Localized category name in a form of a map of translations.


 
object
Localized category description in a form of a map of translations.


 
parentId
string or null
Unique identifier of the parent category. No parentId in the body indicates that this is a root category.


 
object
Provides localized category name or code without diacritics for the URL.


 
ecn
Array of strings or null
List of external category numbers (ECNs) unique for every category.


 
code
string or null
Unique category identifier, defined by the tenant.


 
object
Category's validity.


 
position
integer or null <int32>   >= 0 
Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.


 
published
required
boolean
Flag indicating whether the category has been published or not.


 
object
Custom category attributes that need to be included directly in the mixins object.


 
Responses 
201
The category has been successfully created.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


409
Duplicated ECN value - given ECN is already assigned to another category


post/{tenant}/categories
Request samples 
application/json
{
  • "parentId": "056bcaf6-66b8-4ddd-9489-65c5f6449e74",
  • "localizedName": {
    },
  • "localizedDescription": {
    },
  • "localizedSlug": {
    },
  • "ecn": [
    ],
  • "validity": {
    },
  • "position": 5,
  • "published": true,
  • "mixins": { }
}
Response samples 
application/json
{
  • "id": "084bcaf6-66b8-4ddd-9489-65c5f6449e94"
}
Retrieving a list of categoriesDeprecated
Retrieves a list of categories.




Required scopes


    

  • category.category_read_unpublished
    

      Note: Only required if the response should contain unpublished categories.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]{2,15}$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
query Parameters
expand
string
List of additional attributes to be retrieved for the categories, separated by commas.


Possible values to be passed in this parameter are:


    

  • assignments
    • 

  • subcategories
    • 



Order of the attributes has no influence on the response.


Note: If the expand parameter is set to subcategories, first level descendant categories are retrieved.


 
sort
string
List of properties used to sort the results, separated by commas.


Possible values:


    

  • {fieldName}
    • 

  • {fieldName}:desc
    • 



Note: If the expand parameter passes the subcategories value, sorting is also applied to subcategories.


 
toplevel
boolean
If set to true, only main categories (not assigned to a parent category other than root) are retrieved.


 
Responses 
200
The request was successful. The categories are returned.


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource does not exist.


500
Some server-side error occurred. Details will be provided in the response payload.


get/{tenant}/categories 
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving a category's details
Retrieves a specified category and its details using the category ID.


Note: If you want to retrieve the category details using the code, you can do this by using the GET endpoint for retrieving a list of categories with the code query parameter.




Required scopes


    

  • category.category_read_unpublished
    

    Note: Only required if the response should contain unpublished categories.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
showUnpublished
boolean
 Default:  false
If set to true, not published categories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
Note: To get unpublished categories you need to have category.category_read_unpublished scope.
    • 



 
 Example:  showUnpublished=true
header Parameters
Accept-Language
string
 Default:  *
List of properties used to project and sort the results, separated by commas.
Possible values:


    

  • * - each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.
    • 

  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
    • 

  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
200
The request was successful. The category is returned.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


get/{tenant}/categories/{categoryId}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "parentId": "string",
  • "localizedName": {
    },
  • "localizedDescription": {
    },
  • "localizedSlug": {
    },
  • "name": "string",
  • "description": "string",
  • "code": "string",
  • "ecn": [
    ],
  • "Validity": {
    },
  • "position": 0,
  • "published": true,
  • "supercategoriesIds": [
    ],
  • "mixins": { },
  • "Metadata": {
    },
  • "media": []
}
Updating a category
Fully updates a specified category by replacing existing information.
Version specified in the 'metadata' field must be the same as in the database. Category-to-root promotion may be achieved by adding the 'parentId' field with the 'root' value or by excluding the 'parentId' from the payload.




Required scopes


    

  • category.category_update
    • 

  • category.category_publish
Note: The category.category_publish scope is only required if you want to publish the category when updating it.
    • 

  • category.category_unpublish
Note: Only required if you want to unpublish the category when updating it.
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
publish
boolean
 Default:  false
If set to true category may be published when updated, otherwise may be unpublished. It must match value of 'published' field of the request body.
Possible values:


    

  • true
    • 

  • false
Note: To publish a category you need to have category.category_publish scope.
Note: To unpublish a category you need to have category.category_unpublish scope.
    • 



 
 Example:  publish=true
header Parameters
Content-Language
string
 Default:  *
The Content-Language request HTTP header defines language(s) of the payload. Request body may contain only translations that are matching the languages specified in the header.
Possible values:


    

  • * - request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.
    • 

  • en, en,de, fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - request body may contain only translations for languages specified in the header (if they are available in tenant configuration) .
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Request Body schema: application/json
required
object  non-empty 
Localized category name in a form of a map of translations.


 
object
Localized category description in a form of a map of translations.


 
parentId
string or null
Unique identifier of the parent category. No parentId in the body indicates that this is a root category.


 
object
Provides localized category name or code without diacritics for the URL.


 
ecn
Array of strings or null
List of external category numbers (ECNs) unique for every category.


 
code
string or null
Unique category identifier, defined by the tenant.


 
object
Category's validity.


 
position
integer or null <int32>   >= 0 
Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.


 
published
required
boolean
Flag indicating whether the category has been published or not.


 
object
Custom category attributes that need to be included directly in the mixins object.


 
required
object
Category metadata.


 
Responses 
204
The category has been successfully updated


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


409
Duplicated ECN value - given ECN is already assigned to another category


put/{tenant}/categories/{categoryId}
Request samples 
application/json
{
  • "parentId": "084bcaf6-66b8-4ddd-9489-65c5f6449e94",
  • "localizedName": {
    },
  • "localizedDescription": {
    },
  • "localizedSlug": {
    },
  • "ecn": [
    ],
  • "validity": {
    },
  • "position": 5,
  • "published": true,
  • "mixins": { },
  • "metadata": {
    }
}
Response samples 
application/json
{ }
Deleting a category
Deletes a specified category.


Required scopes


    

  • category.category_delete
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
withSubcategories
boolean
 Default:  false
Deprecated name : "recursive".
If set to true, all descendants of the specified category will be deleted as well.
If set to false, direct subcategories of the specified category will become top-level categories. Relations between the subcategories and their descendants will be preserved.
Possible values:


    

  • true
    • 

  • false
Note: To delete a category you need to have category.category_delete scope.
    • 



 
 Example:  withSubcategories=true
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
204
The category was successfully deleted.


400
Request was logically incorrect. Details will be provided in the response payload.


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


delete/{tenant}/categories/{categoryId}
Request samples 
Response samples 
application/json
{ }
Updating a category
Partially updates a specified category.
Version specified in the 'metadata' field must be the same as in the database. Category-to-root promotion may be achieved by adding 'parentId' field with the 'root' value.




Required scopes


    

  • category.category_update
    • 

  • category.category_publish
Note: The category.category_publish scope is only required if you want to publish the category when creating it.
    • 

  • category.category_unpublish
Note: Only required if you want to unpublish the category when updating it.
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
publish
boolean
 Default:  false
If set to true category may be published when updated, otherwise may be unpublished. It must match value of 'published' field of the request body.
Possible values:


    

  • true
    • 

  • false
Note: To publish a category you need to have category.category_publish scope.
Note: To unpublish a category you need to have category.category_unpublish scope.
    • 



 
 Example:  publish=true
header Parameters
Content-Language
string
 Default:  *
The Content-Language request HTTP header defines language(s) of the payload. Request body may contain only translations that are matching the languages specified in the header.
Possible values:


    

  • * - request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.
    • 

  • en, en,de, fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - request body may contain only translations for languages specified in the header (if they are available in tenant configuration) .
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Request Body schema: application/json
object
Localized category name in a form of a map of translations.


 
object
Localized category description in a form of a map of translations.


 
parentId
string or null
Unique identifier of the parent category. No parentId in the body indicates that this is a root category.


 
object
Provides localized category name or code without diacritics for the URL.


 
ecn
Array of strings or null
List of external category numbers (ECNs) unique for every category.


 
code
string or null
Unique category identifier, defined by the tenant.


 
object
Category's validity.


 
position
integer or null <int32> 
Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.


 
published
boolean or null
Flag indicating whether the category has been published or not.


 
object
Custom category attributes that need to be included directly in the mixins object.


 
required
object
Category metadata.


 
Responses 
204
The category has been successfully updated


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


409
Duplicated ECN value - given ECN is already assigned to another category


patch/{tenant}/categories/{categoryId}
Request samples 
application/json
{
  • "localizedName": {
    },
  • "localizedSlug": {
    },
  • "position": 3,
  • "published": true,
  • "metadata": {
    }
}
Response samples 
application/json
{ }
Retrieving parents for a category
Retrieves a list of parents for a specified category. Parents are sorted in ascending order from root to leaf by default.


If there are unpublished categories in the category tree, then if the parameter showUnpublished=false is used,
unpublished category parents will be omitted in the response.




Required scopes


    

  • category.category_read_unpublished
    

    Note: Only required if the response should contain unpublished categories.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
showUnpublished
boolean
 Default:  false
If set to true, not published categories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
Note: To get unpublished categories you need to have category.category_read_unpublished scope.
    • 



 
 Example:  showUnpublished=true
pageNumber
integer <int32>   >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer <int32>   >= 1 
 Default:  60
Number of export files to be retrieved per page.


 
sort
string
List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden.
Possible values:


    

  • {fieldName}:ASC
    • 

  • {fieldName}:DESC
    • 

  • {fieldName}:ASC,{fieldName2}:DESC
    • 

  • {internationalizedFieldName.en}:ASC - contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.
    • 

  • {internationalizedFieldName}:ASC - contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
    • 



 
 Example:  sort={fieldName}:ASC,{fieldName2}:DESC
header Parameters
Accept-Language
string
 Default:  *
List of properties used to project and sort the results, separated by commas.
Possible values:


    

  • * - each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.
    • 

  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
    • 

  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
X-Total-Count
boolean
 Default:  false
The header value indicates if the total count of entities should be returned.
Possible values:


    

  • true
    • 

  • false
Default value: false
    • 



 
 Example:  true
Responses 
200
The request was successful. The category parents are returned.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


get/{tenant}/categories/{categoryId}/parents
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving subcategories for a category
Retrieves a list of subcategories for a specified category.


If there are unpublished categories in the category tree, then when the showUnpublished=false
parameter is used, only subcategories up to the last published subcategory will be shown.




Required scopes


    

  • category.category_read_unpublished
    

    Note: Only required if the response should contain unpublished categories.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
depth
integer <int32>   >= 0 
You can limit the depth of retrieved subcategories with the depth parameter.
If not specified, all descendant categories are retrieved.
Possible values:


    

  • integer >= 1
    • 



Note: 'depth=1' means that only direct children of the category will be retrieved


 
showUnpublished
boolean
 Default:  false
If set to true, not published categories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
Note: To get unpublished categories you need to have category.category_read_unpublished scope.
    • 



 
 Example:  showUnpublished=true
pageNumber
integer <int32>   >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer <int32>   >= 1 
 Default:  60
Number of export files to be retrieved per page.


 
sort
string
List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden.
Possible values:


    

  • {fieldName}:ASC
    • 

  • {fieldName}:DESC
    • 

  • {fieldName}:ASC,{fieldName2}:DESC
    • 

  • {internationalizedFieldName.en}:ASC - contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.
    • 

  • {internationalizedFieldName}:ASC - contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
    • 



 
 Example:  sort={fieldName}:ASC,{fieldName2}:DESC
header Parameters
Accept-Language
string
 Default:  *
List of properties used to project and sort the results, separated by commas.
Possible values:


    

  • * - each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.
    • 

  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
    • 

  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
X-Total-Count
boolean
 Default:  false
The header value indicates if the total count of entities should be returned.
Possible values:


    

  • true
    • 

  • false
Default value: false
    • 



 
 Example:  true
Responses 
200
The request was successful. The category subcategories are returned.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


get/{tenant}/categories/{categoryId}/subcategories
Request samples 
Response samples 
application/json
[
  • {
    }
]
Category Assignment Resources
Manage Category Assignments


Assigning resources to a category
Assigns resources to a specified category.




Required scopes


    

  • category.category_update
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Request Body schema: application/json
 Array (<= 200 items)
required
object
 
Responses 
207
Multi-status.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


post/{tenant}/categories/{categoryId}/assignments/bulk
Request samples 
application/json
[
  • {
    },
  • {
    }
]
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Retrieving resources assigned to a category
Retrieves resources (such as products) assigned to a specified category.
Localized name field contains resource (product) name. This information is attached to assignment asynchronously and will be visible in the response while getting it.




Required scopes


    

  • category.category_read_unpublished
    

    Note: Only required if the category has not been published.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
assignmentType
string
 Default:  "PRODUCT"
Resource type assigned to the category.
Possible values:


    

  • PRODUCT
    • 



 Value: "PRODUCT"  
ref.localizedName
string
Localized name of the item assigned to the category.


 
 Example:  ref.localizedName=Twix
ref.id
string
Identifier of the item assigned to the category.


 
 Example:  ref.id=5c3348bda9812100098ffaa3
showUnpublished
boolean
 Default:  false
If set to true, resources assigned to not published categories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
Note: To get unpublished categories you need to have category.category_read_unpublished scope.
    • 



 
 Example:  showUnpublished=true
withSubcategories
boolean
 Default:  false
If set to true, resources assigned to subcategories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
    • 



 
 Example:  withSubcategories=true
pageNumber
integer <int32>   >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer <int32>   >= 1 
 Default:  60
Number of export files to be retrieved per page.


 
sort
string
List of properties used to sort the results, separated by commas. This list is validated against available fields. Sorting by deprecated field is forbidden.
Possible values:


    

  • {fieldName}:ASC
    • 

  • {fieldName}:DESC
    • 

  • {fieldName}:ASC,{fieldName2}:DESC
    • 

  • {internationalizedFieldName.en}:ASC - contains localized field name and extension. Valid only if Accepted-language header contains this extension and it is supported by configuration of the tenant. If all language are accepted (Accept-language='*') then extension must exist in tenant configuration. No other sorting are allowed for this specific internationalized field.
    • 

  • {internationalizedFieldName}:ASC - contains only localized field name. Extension will be deducted based on Accept-language header. If all language are accepted (Accept-language='*') then extension is taken from tenant configuration and is equal to default language. In other case the language with highest priority is taken. No other sorting are allowed for this specific localized field.
    • 



 
 Example:  sort={fieldName}:ASC,{fieldName2}:DESC
hideUnpublishedProducts
boolean
 Default:  false
If set to true only assignments with published products will be returned. The default value is false


 
header Parameters
Accept-Language
string
 Default:  *
List of properties used to project and sort the results, separated by commas.
Possible values:


    

  • * - each internationalized field is returned as a map containing all available (specified in tenant configuration) translations. This is also the default behaviour if the header is not set.
    • 

  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
    • 

  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown.
    • 



 
 Example:  `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
X-Total-Count
boolean
 Default:  false
The header value indicates if the total count of entities should be returned.
Possible values:


    

  • true
    • 

  • false
Default value: false
    • 



 
 Example:  true
Responses 
200
The request was successful. The category assignments are returned.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


get/{tenant}/categories/{categoryId}/assignments
Request samples 
Response samples 
application/json
[
  • {
    }
]
Assigning a resource to a category
Assigns a resource to a specified category.




Required scopes


    

  • category.category_update
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Request Body schema: application/json
required
object
Assignment reference.


 
Responses 
201
The resource has been successfully assigned to the category.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


post/{tenant}/categories/{categoryId}/assignments
Request samples 
application/json
{
  • "ref": {
    }
}
Response samples 
application/json
{
  • "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}
Deleting all category assignments
Deletes all assignments for a specified category.




Required scopes


    

  • category.category_update
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
query Parameters
assignmentType
string
 Default:  "PRODUCT"
Resource type assigned to the category.
Possible values:


    

  • PRODUCT
    • 



 Value: "PRODUCT"  
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
204
Assignments has been successfully deleted


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


delete/{tenant}/categories/{categoryId}/assignments
Request samples 
Response samples 
application/json
{
  • "code": 403,
  • "status": "Forbidden",
  • "message": "You need a scope for this action.",
  • "details": [
    ]
}
Deleting a category assignment by id
Deletes an assignment from a specified category.




Required scopes


    

  • category.category_update
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
assignmentId
required
string
Assignment's unique identifier


 
 Example:  1256792345
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
204
Assignment has been successfully deleted.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


delete/{tenant}/categories/{categoryId}/assignments/{assignmentId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Assignment reference validation failed",
  • "details": [
    ]
}
Deleting a category assignment by reference id
Deletes an assignment from a specified category.




Required scopes


    

  • category.category_update
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
Category's unique identifier generated when the category is created.


 
 Example:  084bcaf6-66b8-4ddd-9489-65c5f6449e94
referenceId
required
string
Assignment's reference unique identifier, for example: productId.


 
 Example:  1256792345
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
204
Assignment has been successfully deleted.


400
Request was syntactically incorrect. Details will be provided in the response payload


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category with the specified categoryId does not exist


delete/{tenant}/categories/{categoryId}/assignments/references/{referenceId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Assignment reference validation failed",
  • "details": [
    ]
}
Category Tree Resources
Read Category Trees


Retrieving a category treeDeprecated
Retrieves a category tree.


Note: By default, only published categories are retrieved.




Required scopes:


No specific scopes are required.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]{2,15}$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
Responses 
200
The request was successful. The category tree is returned.


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource does not exist.


500
Some server-side error occurred. Details will be provided in the response payload.


get/{tenant}/categories/categoryTree
Request samples 
Response samples 
application/json
{
  • "id": "38118",
  • "name": "ProductRoot",
  • "code": "productroot",
  • "description": "{\"type\":\"ProductRoot\"}",
  • "position": 55555,
  • "published": true,
  • "subcategories": [
    ]
}
Retrieving the category trees
Retrieves the category trees.




Required scopes


    

  • category.category_read_unpublished
    

    Note: Only required if the response should contain unpublished categories.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
query Parameters
showUnpublished
boolean
 Default:  false
If set to true, not published categories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
Note: To get unpublished categories you need to have category.category_read_unpublished scope.
    • 



 
 Example:  showUnpublished=true
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
200
The request was successful. The category tree is returned.


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


get/{tenant}/category-trees
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving a specific category tree
Retrieves a category tree for a root category with a given id.


Note: You can retrieve a category tree only for a root category. It is not possible to get a category tree for a category that lies lower in the hierarchy.




Required scopes


    

  • category.category_read_unpublished
    

    Note: Only required if the response should contain unpublished categories.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
A unique identifier of a root category, generated when the category is created.


 
 Example:  12a24ba108-e6fd-4139-b831-5ac5fded6d34
query Parameters
showUnpublished
boolean
 Default:  false
If set to true, not published categories are retrieved as well.
Possible values:


    

  • true
    • 

  • false
Note: To get unpublished categories you need to have category.category_read_unpublished scope.
    • 



 
 Example:  showUnpublished=true
header Parameters
X-Version
required
string^v[1-9][0-9]?$
To use this endpoint you have to add X-Version header with proper value to your request.


Note: The header value has to match following regular expression: ^v[1-9][0-9]?$


 
 Example:  v2
Responses 
200
The request was successful. The category tree is returned.


403
Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.


404
Category tree with specified id does not exist


get/{tenant}/category-trees/{categoryId}
Request samples 
Response samples 
application/json
{
  • "id": "46124ba108-e6fd-4139-b831-5ac5fded6d52",
  • "localizedName": {
    },
  • "code": "productroot",
  • "localizedSlug": {
    },
  • "localizedDescription": {
    },
  • "position": 55555,
  • "published": true,
  • "subcategories": [
    ]
}