Items Assignments

Manage item assignments to segments

Retrieving category trees for a customer segments

get

Retrieves category trees for the customer segments. Category trees are built based on only active segments.

Required scopes

• customersegment.segment_read_own - allows customers to access categories that are assigned to the active segments they belong to

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

legalEntityIdstringOptional

The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.

siteCodestringOptional

The parameter is utilized for searching in relation to the siteCode. Only items will be returned which are assigned to segment from given siteCode.

Header parameters

Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer categories assignments were successfully retrieved.

application/json

idstringRequired

Unique identifier of an existing category.

codestringRequired

Unique code of an existing category.

ecnstring[]Optional

List of external category numbers (ECNs) unique for every category.

positionintegerOptional

Category's position, set in relation to the categories on the same level (sharing the same parent) in the tree.

publishedbooleanOptional

Indicates whether the category has been published or not.

isSegmentAssignedbooleanRequired

Indicates if the category is assigned to any segment.

subcategoriesobject[]Optional

Subcategories of this category.

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

get

/customer-segment/{tenant}/segments/items/category-trees

HTTPcURLJavaScriptPython

GET /customer-segment/{tenant}/segments/items/category-trees HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "12468504",
    "code": "123",
    "name": {
      "en": "Tools"
    },
    "position": 0,
    "published": true,
    "isSegmentAssigned": false,
    "subcategories": [
      {
        "id": "12468505",
        "parentId": "12468504",
        "code": "234",
        "name": {
          "en": "Hammer"
        },
        "localizedDescription": {
          "en": "Basic and professional-grade hammers for construction and home improvement tasks."
        },
        "validity": {
          "from": "2024-04-17T08:00:00.000Z",
          "to": "2026-04-17T08:00:00.000Z"
        },
        "position": 1,
        "published": true,
        "isSegmentAssigned": true,
        "subcategories": [
          {
            "id": "12468506",
            "parentId": "12468505",
            "code": "345",
            "name": {
              "en": "Sledgehammers"
            },
            "position": 2,
            "published": true,
            "isSegmentAssigned": true
          }
        ]
      }
    ]
  }
]

Retrieving all items assignments for all customer segments

get

Retrieves all items assignments for all customer segments.

Required scopes

• customersegment.segment_read_own - allows customers to access items that are assigned to the active segments they belong to

• customersegment.segment_read - allows to access all items

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard practises - Query parameter

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

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

fieldsstringOptional

Fields to be returned in the response.

legalEntityIdstringOptional

The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.

siteCodestringOptional

The parameter is utilized for searching in relation to the siteCode. Only items will be returned which are assigned to segment from given siteCode.

onlyActivebooleanOptional

The parameter is utilized for filtering items which belong only to active segments. The parameter is always true for users with customersegment.segment_read_own scope.

Default: false

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer items assignments were successfully retrieved.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

get

/customer-segment/{tenant}/segments/items

HTTPcURLJavaScriptPython

GET /customer-segment/{tenant}/segments/items HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "segmentId": "segmentId",
    "item": {
      "id": "12468504",
      "code": "123",
      "name": {
        "en": "Hammer"
      }
    },
    "type": "PRODUCT",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  },
  {
    "segmentId": "segmentId",
    "item": {
      "id": "12849186",
      "code": "456",
      "name": {
        "en": "Screwdriver"
      }
    },
    "type": "PRODUCT",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  }
]

Retrieving all item assignments for a customer segment

get

Retrieves all item assignments for a given customer segment.

Required scopes

• customersegment.segment_read - allows you to retrieve all item assignments

• customersegment.segment_read_own - allows customers to access items that are assigned to the active segment they belong to

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

Query parameters

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard practises - Query parameter

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

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

fieldsstringOptional

Fields to be returned in the response.

legalEntityIdstringOptional

The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer segment assignments were successfully retrieved.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

get

/customer-segment/{tenant}/segments/{segmentId}/items

HTTPcURLJavaScriptPython

GET /customer-segment/{tenant}/segments/{segmentId}/items HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "segmentId": "segmentId",
    "item": {
      "id": "12468504",
      "code": "123",
      "name": {
        "en": "Hammer"
      }
    },
    "type": "PRODUCT",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  },
  {
    "segmentId": "segmentId",
    "item": {
      "id": "12849186",
      "code": "456",
      "name": {
        "en": "Screwdriver"
      }
    },
    "type": "PRODUCT",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  }
]

Retrieving all item assignments for a customer segment

post

Retrieves all item assignments for a given customer segment.

Required scopes

• customersegment.segment_read - allows you to retrieve all item assignments

• customersegment.segment_read_own - allows customers to access items that are assigned to the active segment they belong to

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

Query parameters

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

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

fieldsstringOptional

Fields to be returned in the response.

legalEntityIdstringOptional

The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Body

application/json

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard practises - Query parameter

Responses

200

Customer segment assignments were successfully retrieved.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

post

/customer-segment/{tenant}/segments/{segmentId}/items/search

HTTPcURLJavaScriptPython

POST /customer-segment/{tenant}/segments/{segmentId}/items/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "q": "type:PRODUCT"
}

[
  {
    "segmentId": "segmentId",
    "item": {
      "id": "12468504",
      "code": "123",
      "name": {
        "en": "Hammer"
      }
    },
    "type": "PRODUCT",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  },
  {
    "segmentId": "segmentId",
    "item": {
      "id": "12849186",
      "code": "456",
      "name": {
        "en": "Screwdriver"
      }
    },
    "type": "PRODUCT",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  }
]

Retrieving an item assignment

get

Retrieves an item assignment by specified ID for a given customer segment.

Required scopes

• customersegment.segment_read - allows you to retrieve an item assignment

• customersegment.segment_read_own - allows customers to access item that is assigned to the active segment they belong to

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

typestringRequired

Determines whether item is a product or category.

itemIdstringRequired

Unique identifier of an item which will be assigned to a customer segment.

Query parameters

fieldsstringOptional

Fields to be returned in the response.

legalEntityIdstringOptional

The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.

Header parameters

Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses

200

Customer segment item assignment was successfully retrieved.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

404

Resource not found

application/json

get

/customer-segment/{tenant}/segments/{segmentId}/items/{type}/{itemId}

HTTPcURLJavaScriptPython

GET /customer-segment/{tenant}/segments/{segmentId}/items/{type}/{itemId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "segmentId": "segmentId",
  "item": {
    "id": "12468504",
    "code": "123",
    "name": {
      "en": "Hammer"
    }
  },
  "type": "PRODUCT",
  "metadata": {
    "createdAt": "2024-10-12T12:00:00.000Z",
    "modifiedAt": "2024-10-12T12:00:00.000Z",
    "version": 1
  }
}

Updating an item assignment

put

Performs UPSERT operation. Updates an item assignment to a customer segment. A new item assignment is created if it's not present in the system.

Required scopes

• customersegment.segment_manage - required to add and modify item assignments

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

typestringRequired

Determines whether item is a product or category.

itemIdstringRequired

Unique identifier of an item which will be assigned to a customer segment.

Body

application/json

Responses

201

A new assignment was successfully created.

204

Item assignment was successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

409

Conflict

application/json

put

/customer-segment/{tenant}/segments/{segmentId}/items/{type}/{itemId}

HTTPcURLJavaScriptPython

PUT /customer-segment/{tenant}/segments/{segmentId}/items/{type}/{itemId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 216

{
  "mixins": {
    "segmentAttributes": {
      "membershipStatus": "PREMIUM"
    }
  },
  "metadata": {
    "mixins": {
      "segmentAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/69537caeb3fd5d378296ae42_segmentAttributes.json"
    }
  }
}

No content

Removing an assignment

delete

Removes an item assignment.

Required scopes

• customersegment.segment_manage - required to delete item assignments

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

typestringRequired

Determines whether item is a product or category.

itemIdstringRequired

Unique identifier of an item which will be assigned to a customer segment.

Responses

204

Item assignment was successfully removed.

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

delete

/customer-segment/{tenant}/segments/{segmentId}/items/{type}/{itemId}

HTTPcURLJavaScriptPython

DELETE /customer-segment/{tenant}/segments/{segmentId}/items/{type}/{itemId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Updating item assignments to a customer segment in bulk

put

Performs UPSERT operation. Updates multiple item assignments to a customer segments. The maximum batch size is 200.

Required scopes

• customersegment.segment_manage - required to add and modify item assignments

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

typestringRequired

Determines whether item is a product or category.

Bodyall of[]

application/json

Responses

207

Multi-status response.

application/json

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

put

/customer-segment/{tenant}/segments/{segmentId}/items/{type}/bulk

HTTPcURLJavaScriptPython

PUT /customer-segment/{tenant}/segments/{segmentId}/items/{type}/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 277

[
  {
    "id": "12468504",
    "mixins": {
      "segmentAttributes": {
        "membershipStatus": "PREMIUM"
      }
    },
    "metadata": {
      "mixins": {
        "segmentAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/69537caeb3fd5d378296ae42_segmentAttributes.json"
      }
    }
  },
  {
    "id": "12849186",
    "metadata": {
      "version": 2
    }
  }
]

[
  {
    "index": 1,
    "code": 204,
    "status": "OK"
  },
  {
    "index": 2,
    "code": 400,
    "status": "Bad Request",
    "message": "Validation problem with request body."
  }
]

Deleting item assignments to a customer segment in bulk

delete

Removes multiple customer segments item assignments. The maximum batch size is 200.

• The IDs of items should be defined in the request body as an array of strings. Example: ["firstItemId", "secondItemId", "thirdItemId"]

Required scopes

• customersegment.segment_manage - required to delete item assignments

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

typestringRequired

Determines whether item is a product or category.

Responses

207

Multi-status response.

application/json

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

delete

/customer-segment/{tenant}/segments/{segmentId}/items/{type}/bulk

HTTPcURLJavaScriptPython

DELETE /customer-segment/{tenant}/segments/{segmentId}/items/{type}/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "index": 1,
    "code": 204,
    "status": "OK"
  },
  {
    "index": 2,
    "code": 204,
    "status": "OK"
  }
]