CommunitySupport PortalYouTubeStart a free trial

Segments

Manage segments

Retrieving all customer segments

get

Retrieves all customer segments.

Required scopes

  • customersegment.segment_read - allows you to retrieve all customer segments

  • customersegment.segment_read_own - allows customers to retrieve active customer segments which they are assigned 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
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 segments were successfully retrieved.
application/json
get
GET /customer-segment/{tenant}/segments HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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

  • customersegment.segment_manage - required to create a customer segment

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]+$
Header parameters
Content-LanguagestringOptional

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

Example: en
Body
all ofOptional
Responses
201
Customer segment was successfully created.
application/json
post
POST /customer-segment/{tenant}/segments HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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

  • customersegment.segment_read - allows you to retrieve all customer segments

  • customersegment.segment_read_own - allows customers to retrieve customer segments which they are assigned 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
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 segments were successfully retrieved.
application/json
post
POST /customer-segment/{tenant}/segments/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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

  • customersegment.segment_read - allows you to retrieve a customer segment

  • customersegment.segment_read_own - allows customers to retrieve active customer segment which they are assigned 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
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
Responseall of
get
GET /customer-segment/{tenant}/segments/{segmentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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

  • customersegment.segment_manage - required to update a customer segment

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.

Header parameters
Content-LanguagestringOptional

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

Example: en
Body
all ofOptional
Responses
201
Customer segment wasn't found. A new customer segment was successfully created.
application/json
put
PUT /customer-segment/{tenant}/segments/{segmentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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

  • customersegment.segment_manage - required to delete a customer segment

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
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.
delete
DELETE /customer-segment/{tenant}/segments/{segmentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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

  • customersegment.segment_manage - required to update a customer segment

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.

Header parameters
Content-LanguagestringOptional

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

Example: en
Bodyobject[]
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.
patch
PATCH /customer-segment/{tenant}/segments/{segmentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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.

Required scopes

  • customersegment.segment_manage - required to create customer segments

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]+$
Header parameters
Content-LanguagestringOptional

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

Example: en
Bodyall of[]
itemsall ofOptional
Responses
207
Multi-status response.
application/json
post
POST /customer-segment/{tenant}/segments/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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.

Required scopes

  • customersegment.segment_manage - required to update customer segments

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]+$
Header parameters
Content-LanguagestringOptional

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

Example: en
Bodyall of[]
itemsall ofOptional
Responses
207
Multi-status response.
application/json
put
PUT /customer-segment/{tenant}/segments/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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 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

  • customersegment.segment_manage - required to delete customer segments

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
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
delete
DELETE /customer-segment/{tenant}/segments/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
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

  • customersegment.segment_manage - required to check if items match criteria.

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]+$
Body
segmentIdsstring[]Required
sitestringRequired
Responses
200
Id of the products which match criteria.
application/json
post
POST /customer-segment/{tenant}/segments/match HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

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

Was this helpful?