Category

Download OpenAPI specification:Download

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
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,
  • "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

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": [
    ]
}