Segments

Manage segments

Retrieving all customer segments

get

Retrieves all customer segments.

Required scopes

This endpoint requires the following scopes:

Authorizations

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.

customerIdstringOptional

The parameter is utilized for retrieving customer segments for a provided customer.

NOTE: This parameter can only be used with customersegment.segment_read scope.

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 segments were successfully retrieved.

application/json

idstringOptional

Unique identifier of the customer segment.

statusstring · enumOptional

Determines whether the customer segment is active or not. If not provided the value is set to INACTIVE

Possible values:

siteCodestringRequired

Determines for which site the customer segment is available.

401

Unauthorized

application/json

403

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

application/json

get/customer-segment/{tenant}/segments

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

[
  {
    "id": "628cd20c6e8b2432b6346ca6",
    "name": {
      "en": "Golden Segment"
    },
    "description": {
      "en": "Golden Segment"
    },
    "validity": {
      "from": "2024-04-17T08:00:00.000Z",
      "to": "2025-04-17T08:00:00.000Z"
    },
    "status": "ACTIVE",
    "siteCode": "main",
    "metadata": {
      "createdAt": "2024-05-14T12:00:00.000Z",
      "modifiedAt": "2024-05-14T12:00:00.000Z",
      "version": 1
    }
  },
  {
    "id": "61ge81e13562e22001h6cf456",
    "name": {
      "en": "Platinum Segment"
    },
    "description": {
      "en": "Platinum Segment"
    },
    "validity": {
      "from": "2024-07-20T08:00:00.000Z",
      "to": "2025-07-20T08:00:00.000Z"
    },
    "status": "INACTIVE",
    "siteCode": "main",
    "metadata": {
      "createdAt": "2024-05-14T12:00:00.000Z",
      "modifiedAt": "2024-05-14T12:00:00.000Z",
      "version": 1
    }
  }
]

Creating a customer segment

post

Creates a new customer segment.

Required scopes

This endpoint requires the following scopes:

Authorizations

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]+$

Header parameters

Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Body

idstringOptional

Unique identifier of the customer segment. It will be auto-generated if not provided.

statusstring · enumOptional

Determines whether the customer segment is active or not. If not provided the value is set to INACTIVE

Possible values:

siteCodestringRequired

Determines for which site the customer segment is available.

Responses

201

Customer segment was successfully created.

application/json

idstringOptional

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

post/customer-segment/{tenant}/segments

POST /customer-segment/{tenant}/segments HTTP/1.1
Host: api.emporix.io
Content-Type: application/json
Accept: */*
Content-Length: 217

{
  "id": "628cd20c6e8b2432b6346ca6",
  "name": {
    "en": "Golden Segment"
  },
  "description": {
    "en": "Golden Segment"
  },
  "validity": {
    "from": "2024-04-17T08:00:00.000Z",
    "to": "2025-04-17T08:00:00.000Z"
  },
  "status": "ACTIVE",
  "siteCode": "main"
}

{
  "id": "628cd20c6e8b2432b6346ca6"
}

Searching with parameters for customer segments

post

Returns all customer segments that match provided criteria.

Required scopes

This endpoint requires the following scopes:

Authorizations

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

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.

customerIdstringOptional

The parameter is utilized for retrieving customer segments for a provided customer.

NOTE: This parameter can only be used with customersegment.segment_read scope.

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 segments were successfully retrieved.

application/json

idstringOptional

Unique identifier of the customer segment.

statusstring · enumOptional

Determines whether the customer segment is active or not. If not provided the value is set to INACTIVE

Possible values:

siteCodestringRequired

Determines for which site the customer segment is available.

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

post/customer-segment/{tenant}/segments/search

POST /customer-segment/{tenant}/segments/search HTTP/1.1
Host: api.emporix.io
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "q": "siteCode:main"
}

[
  {
    "id": "628cd20c6e8b2432b6346ca6",
    "name": {
      "en": "Golden Segment"
    },
    "description": {
      "en": "Golden Segment"
    },
    "validity": {
      "from": "2024-04-17T08:00:00.000Z",
      "to": "2025-04-17T08:00:00.000Z"
    },
    "status": "ACTIVE",
    "siteCode": "main",
    "metadata": {
      "createdAt": "2024-05-14T12:00:00.000Z",
      "modifiedAt": "2024-05-14T12:00:00.000Z",
      "version": 1
    }
  },
  {
    "id": "61ge81e13562e22001h6cf456",
    "name": {
      "en": "Platinum Segment"
    },
    "description": {
      "en": "Platinum Segment"
    },
    "validity": {
      "from": "2024-07-20T08:00:00.000Z",
      "to": "2025-07-20T08:00:00.000Z"
    },
    "status": "INACTIVE",
    "siteCode": "main",
    "metadata": {
      "createdAt": "2024-05-14T12:00:00.000Z",
      "modifiedAt": "2024-05-14T12:00:00.000Z",
      "version": 1
    }
  }
]

Retrieving a customer segment

get

Retrieves segment with specified ID.

Required scopes

This endpoint requires the following scopes:

Authorizations

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

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 successfully retrieved.

application/json

idstringOptional

Unique identifier of the customer segment.

statusstring · enumOptional

Determines whether the customer segment is active or not. If not provided the value is set to INACTIVE

Possible values:

siteCodestringRequired

Determines for which site the customer segment is available.

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}

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

{
  "id": "628cd20c6e8b2432b6346ca6",
  "name": {
    "en": "Golden Segment"
  },
  "description": {
    "en": "Golden Segment"
  },
  "validity": {
    "from": "2024-04-17T08:00:00.000Z",
    "to": "2025-04-17T08:00:00.000Z"
  },
  "status": "ACTIVE",
  "siteCode": "main",
  "metadata": {
    "createdAt": "2024-05-14T12:00:00.000Z",
    "modifiedAt": "2024-05-14T12:00:00.000Z",
    "version": 1
  }
}

Upserting a customer segment

put

Performs the UPSERT operation. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.

Required scopes

This endpoint requires the following scopes:

Authorizations

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.

Header parameters

Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Body

statusstring · enumOptional

Determines whether the customer segment is active or not. If not provided the value is set to INACTIVE

Possible values:

siteCodestringRequired

Determines for which site the customer segment is available.

Responses

201

Customer segment wasn't found. A new customer segment was successfully created.

application/json

idstringOptional

204

Customer segment 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}

PUT /customer-segment/{tenant}/segments/{segmentId} HTTP/1.1
Host: api.emporix.io
Content-Type: application/json
Accept: */*
Content-Length: 210

{
  "name": {
    "en": "Golden Segment"
  },
  "description": {
    "en": "Golden Segment"
  },
  "validity": {
    "from": "2024-04-17T08:00:00.000Z",
    "to": "2025-04-17T08:00:00.000Z"
  },
  "status": "ACTIVE",
  "siteCode": "main",
  "metadata": {
    "version": 1
  }
}

{
  "id": "628cd20c6e8b2432b6346ca6"
}

Deleting a customer segment

delete

Removes segment with specified ID.

Important: If you want to delete a segment that has items or customers assigned to it, you need to set the forceDelete query parameter to true. In this case, all items and customers assignments will be deleted as well.

Required scopes

This endpoint requires the following scopes:

Authorizations

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

forceDeletebooleanOptional

• If set to true and the segment has items or customers assigned to it, both the segment and the segment assignments will be deleted.
• If set to false or not specified and the segment has items or customers assigned to it, the endpoint will respond with the 400 error.

Default: false

Responses

204

Customer segment was successfully deleted.

No content

401

Unauthorized

application/json

403

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

application/json

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

DELETE /customer-segment/{tenant}/segments/{segmentId} HTTP/1.1
Host: api.emporix.io
Accept: */*

No content

Patching a customer segment

patch

Performs partial update of a segment.

The patch request consists of set of operation, that should be defined according to RFC-6902 standard.

Required scopes

This endpoint requires the following scopes:

Authorizations

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.

Header parameters

Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Bodyobject · PatchOperation[]

opstring · enumRequired

Indicates an operation which should be done on a return. Available operations: add remove and replace

Possible values:

pathstringRequired

Indicates a path for which the value should be applied. For example:/mixins/additionalAttributes/externalId, /name, /status

valueone ofOptional

Indicates a value that should be changed or added. The value can be of a primitive type, like string, number, boolean or it can be an object or an array.

objectOptional

or

stringOptional

or

numberOptional

Responses

204

Customer segment was successfully updated.

No content

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

404

Resource not found

application/json

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

PATCH /customer-segment/{tenant}/segments/{segmentId} HTTP/1.1
Host: api.emporix.io
Content-Type: application/json
Accept: */*
Content-Length: 54

[
  {
    "op": "replace",
    "path": "/status",
    "value": "INACTIVE"
  }
]

No content

Creating customer segments in bulk

post

Creates multiple customer segments. The maximum batch size is 200.

Required scopes

This endpoint requires the following scopes:

Authorizations

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]+$

Header parameters

Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Bodyall of[]

idstringOptional

Unique identifier of the customer segment. It will be auto-generated if not provided.

statusstring · enumOptional

Determines whether the customer segment is active or not. If not provided the value is set to INACTIVE

Possible values:

siteCodestringRequired

Determines for which site the customer segment is available.

Responses

207

Multi-status response.

application/json

idstringOptional

Item's unique identifier.

indexintegerOptional

Index of the processed item, matching the item position in request body.

codeintegerOptional

HTTP Status Code.

statusstringOptional

HTTP Status description.

messagestringOptional

Error message.

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

post/customer-segment/{tenant}/segments/bulk

POST /customer-segment/{tenant}/segments/bulk HTTP/1.1
Host: api.emporix.io
Content-Type: application/json
Accept: */*
Content-Length: 444

[
  {
    "id": "628cd20c6e8b2432b6346ca6",
    "name": {
      "en": "Golden Segment"
    },
    "description": {
      "en": "Golden Segment"
    },
    "validity": {
      "from": "2024-04-17T08:00:00.000Z",
      "to": "2025-04-17T08:00:00.000Z"
    },
    "status": "ACTIVE",
    "siteCode": "main"
  },
  {
    "id": "61ge81e13562e22001h6cf456",
    "name": {
      "en": "Platinum Segment"
    },
    "description": {
      "en": "Platinum Segment"
    },
    "validity": {
      "from": "2024-07-20T08:00:00.000Z",
      "to": "2025-07-20T08:00:00.000Z"
    },
    "status": "INACTIVE",
    "siteCode": "main"
  }
]

[
  {
    "index": 1,
    "id": "628cd20c6e8b2432b6346ca6",
    "code": 201,
    "status": "Created"
  },
  {
    "index": 2,
    "code": 400,
    "status": "Bad Request",
    "message": "Validation problem with request body."
  }
]

Upserting customer segments in bulk

put

Performs the UPSERT operation for multiple customer segments. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.

The maximum batch size is 200.

Required scopes

This endpoint requires the following scopes:

Authorizations

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]+$

Header parameters

Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) of the payload.

Example: en

Bodyall of[]

idstringOptional

Unique identifier of the customer segment.

statusstring · enumOptional

Determines whether the customer segment is active or not. If not provided the value is set to INACTIVE

Possible values:

siteCodestringRequired

Determines for which site the customer segment is available.

Responses

207

Multi-status response.

application/json

idstringOptional

Item's unique identifier.

indexintegerOptional

Index of the processed item, matching the item position in request body.

codeintegerOptional

HTTP Status Code.

statusstringOptional

HTTP Status description.

messagestringOptional

Error message.

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/bulk

PUT /customer-segment/{tenant}/segments/bulk HTTP/1.1
Host: api.emporix.io
Content-Type: application/json
Accept: */*
Content-Length: 494

[
  {
    "id": "628cd20c6e8b2432b6346ca6",
    "name": {
      "en": "Golden Segment"
    },
    "description": {
      "en": "Golden Segment"
    },
    "validity": {
      "from": "2024-04-17T08:00:00.000Z",
      "to": "2025-04-17T08:00:00.000Z"
    },
    "status": "ACTIVE",
    "siteCode": "main",
    "metadata": {
      "version": 1
    }
  },
  {
    "id": "61ge81e13562e22001h6cf456",
    "name": {
      "en": "Platinum Segment"
    },
    "description": {
      "en": "Platinum Segment"
    },
    "validity": {
      "from": "2024-07-20T08:00:00.000Z",
      "to": "2025-07-20T08:00:00.000Z"
    },
    "status": "INACTIVE",
    "siteCode": "main",
    "metadata": {
      "version": 2
    }
  }
]

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

Deleting customer segments in bulk

delete

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

The IDs of customer segments for deletion should be defined in the request body as an array of strings.

Example: ["firstId", "secondId", "thirdId"]

Important: If you want to delete a segment that has items or customers assigned to it, you need to set the forceDelete query parameter to true. In this case, all items and customers assignments will be deleted as well.

Required scopes

This endpoint requires the following scopes:

Authorizations

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

forceDeletebooleanOptional

• If set to true and the segment has items or customers assigned to it, both the segment and the segment assignments will be deleted.
• If set to false or not specified and the segment has items or customers assigned to it, the endpoint will respond with the 400 error.

Default: false

Responses

207

Multi-status response.

application/json

idstringOptional

Item's unique identifier.

indexintegerOptional

Index of the processed item, matching the item position in request body.

codeintegerOptional

HTTP Status Code.

statusstringOptional

HTTP Status description.

messagestringOptional

Error message.

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/bulk

DELETE /customer-segment/{tenant}/segments/bulk HTTP/1.1
Host: api.emporix.io
Accept: */*

[
  {
    "index": 1,
    "id": "628cd20c6e8b2432b6346ca6",
    "code": 204,
    "status": "OK"
  },
  {
    "index": 2,
    "id": "61ge81e13562e22001h6cf456",
    "code": 204,
    "status": "OK"
  }
]

Checking which items belong to segment

post

Checks if the provided items match specified criteria - if ids of the products are assigned directly to one of the provided segments or indirectly through the category assignment. Only items assigned to the active segments will be returned.

Required scopes

This endpoint requires the following scopes:

Authorizations

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]+$

Body

segmentIdsstring[]Required

sitestringRequired

Responses

200

Id of the products which match criteria.

application/json

idstringOptional

Id of the product.

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

post/customer-segment/{tenant}/segments/match

POST /customer-segment/{tenant}/segments/match HTTP/1.1
Host: api.emporix.io
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "siteCode": "main",
  "items": [
    {
      "id": "p1234"
    },
    {
      "id": "p2345"
    }
  ],
  "segmentIds": [
    "S1234",
    "S2456"
  ]
}

[
  {
    "id": "p1234"
  }
]