Category Assignment Resources

Manage Category Assignments

Updating assignment of resources to a category

put

Assigns resources to a specified category in bulk. Assignments that do not exist will be created and existing ones will be updated.


Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Header parameters
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
Bodyobject[]
Responses
207
Multi-status.
application/json
put
PUT /category/{tenant}/categories/{categoryId}/assignments/references/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Content-Type: application/json
Accept: */*
Content-Length: 51

[
  {
    "ref": {
      "id": "1639265"
    }
  },
  {
    "ref": {
      "id": "1639266"
    }
  }
]
[
  {
    "assignmentId": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "productId": "123456",
    "index": 0,
    "code": 201,
    "status": "CREATED"
  },
  {
    "assignmentId": "e333dc9e-a3f6-4573-bb01-a8ae21d2d443",
    "productId": "234567",
    "index": 1,
    "code": 201,
    "status": "CREATED"
  }
]

Assigning resources to a category

post

Assigns resources to a specified category.


Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Header parameters
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
Bodyobject[]
Responses
207
Multi-status.
application/json
post
POST /category/{tenant}/categories/{categoryId}/assignments/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Content-Type: application/json
Accept: */*
Content-Length: 85

[
  {
    "ref": {
      "id": "1639265",
      "type": "PRODUCT"
    }
  },
  {
    "ref": {
      "id": "1639266",
      "type": "PRODUCT"
    }
  }
]
[
  {
    "assignmentId": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae",
    "productId": "123456",
    "index": 0,
    "code": 201,
    "status": "CREATED"
  },
  {
    "assignmentId": "e333dc9e-a3f6-4573-bb01-a8ae21d2d443",
    "productId": "234567",
    "index": 1,
    "code": 201,
    "status": "CREATED"
  }
]

Retrieving resources assigned to a category

get

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.

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
assignmentTypestring · enumOptional

Resource type assigned to the category. Possible values:

  • PRODUCT
Default: PRODUCTPossible values:
ref.localizedNamestringOptional

Localized name of the item assigned to the category.

Example: Twix
ref.idstringOptional

Identifier of the item assigned to the category.

Example: 5c3348bda9812100098ffaa3
showUnpublishedbooleanOptional

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.
Default: falseExample: true
withSubcategoriesbooleanOptional

If set to true, resources assigned to subcategories are retrieved as well. Possible values:

  • true
  • false
Default: falseExample: true
segmentsIdsstringOptional

List of segment IDs used to filter assignments — only category assignments will be returned, where the category is assigned to the provided list of segments.

Example: segmentId1,segmentId2
pageNumberinteger · int32 · min: 1Optional

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.

Default: 1
pageSizeinteger · int32 · min: 1Optional

Number of export files to be retrieved per page.

Default: 60
sortstringOptional

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: {fieldName}:ASC,{fieldName2}:DESC
hideUnpublishedProductsbooleanOptional

If set to true only assignments with published products will be returned. The default value is false

Default: false
Header parameters
Accept-LanguagestringOptional

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.
Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
X-Total-CountbooleanOptional

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

  • true
  • false Default value: false
Default: falseExample: true
Responses
200
The request was successful. The category assignments are returned.
application/json
get
GET /category/{tenant}/categories/{categoryId}/assignments HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
[
  {
    "id": "d7d1745d-6b46-40a7-87d8-ecb60b8260f6",
    "categoryId": "d7d1745d-6b46-40a7-87d8-ecb60b8260f5",
    "ref": {
      "id": "521266ca-a411-4550-a7ab-aeeb4ce74133",
      "type": "PRODUCT",
      "localizedName": {
        "en": "product name"
      }
    }
  }
]

Assigning a resource to a category

post

Assigns a resource to a specified category.


Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Header parameters
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
Body
refall ofRequired
and
anyOptional

Assignment reference.

Responses
201
The resource has been successfully assigned to the category.
application/json
post
POST /category/{tenant}/categories/{categoryId}/assignments HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "ref": {
    "id": "1639265",
    "type": "PRODUCT"
  }
}
{
  "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}

Deleting all category assignments

delete

Deletes all assignments for a specified category.


Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Query parameters
assignmentTypestring · enumOptional

Resource type assigned to the category. Possible values:

  • PRODUCT
Default: PRODUCTPossible values:
Header parameters
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
Responses
204
Assignments has been successfully deleted
delete
DELETE /category/{tenant}/categories/{categoryId}/assignments HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*

No content

Deleting a category assignment by id

delete

Deletes an assignment from a specified category.


Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
assignmentIdstringRequired

Assignment's unique identifier

Example: 1256792345
Header parameters
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
Responses
204
Assignment has been successfully deleted.
delete
DELETE /category/{tenant}/categories/{categoryId}/assignments/{assignmentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*

No content

Upserting a resource to a category assignment

put

Creates or updates an assignment of a resource to a specified category. If any assignment with given categoryId and referenceId does not exist then a new assignment is created.


Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
referenceIdstringRequired

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

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
Header parameters
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
Responses
201
The resource has been successfully assigned to the category.
application/json
put
PUT /category/{tenant}/categories/{categoryId}/assignments/references/{referenceId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*
{
  "id": "e243dc9e-a3f6-4573-bb01-a8ae21d2d4ae"
}

Deleting a category assignment by reference id

delete

Deletes an assignment from a specified category.


Required scopes

  • category.category_manage

Authorizations
Path parameters
tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
categoryIdstringRequired

Category's unique identifier generated when the category is created.

Example: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
referenceIdstringRequired

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

Example: 1256792345
Header parameters
X-VersionstringRequired

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: v2Pattern: ^v[1-9][0-9]?$
Responses
204
Assignment has been successfully deleted.
delete
DELETE /category/{tenant}/categories/{categoryId}/assignments/references/{referenceId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: v2
Accept: */*

No content

Was this helpful?