CommunitySupport PortalYouTubeStart a free trial

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
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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
get
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
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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
get
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
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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
get
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
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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
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
post
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
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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
Responseall of
get
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
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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
all ofOptional
Responses
201
A new assignment was successfully created.
put
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: 202

{
  "mixins": {
    "segmentAttributes": {
      "membershipStatus": "PREMIUM"
    }
  },
  "metadata": {
    "mixins": {
      "segmentAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/segmentAttributes_v1.json"
    }
  }
}
No content

Removing an assignment

delete

Removes an item assignment.

Required scopes

  • customersegment.segment_manage - required to delete item assignments

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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.
delete
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.

Required scopes

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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[]
idstringRequired

Unique identifier of an existing product/category (itemId).

Responses
207
Multi-status response.
application/json
put
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: 263

[
  {
    "id": "12468504",
    "mixins": {
      "segmentAttributes": {
        "membershipStatus": "PREMIUM"
      }
    },
    "metadata": {
      "mixins": {
        "segmentAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/segmentAttributes_v1.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 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
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant's 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
delete
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"
  }
]
PreviousCustomers AssignmentsNextModels

Was this helpful?