Configuring User Segmentation

User segmentation is a feature that allows businesses to define specific rules to categorize users into different groups based on their characteristics. This segmentation helps in assigning customized pricing and stock availability to different user groups. If a user qualifies for multiple segments, the system applies rules in order of priority, assigning the user to the first matching segment. This document outlines the necessary steps to configure user segmentation and how to make requests.

Steps to Configure User Segmentation

1. Define Segmentation Rules (Required)

To start with user segmentation, you must define the rules that determine how users will be segmented. You can find more details on the rule configuration process in the User Segmentation document.

Rule-based segmentation: The first rule that matches a user will apply, so make sure to set priorities for your rules.

1. Price and Stock Lists (Optional)

If you do not provide custom price and stock lists, the default catalog lists will be used.

You can create extra price and stock lists if needed. These lists should have a specific code and can be added through the UI or via a POST/PATCH request using this APIs.

1. Priority Configuration

Each user can only belong to one segment. The priority determines which rule will be applied if a user fits multiple segments. Rules will be evaluated in order of priority, and the first matching rule will assign the user to a segment. More details about rule prioritization can be found here.

1. Custom Price and Stock List Management

To use custom price and stock lists, they need to be associated with a specific code. These custom lists should be added to the catalog. After adding, it may take some time for the lists to sync with the catalog, and only after syncing will they appear under the relevant segment’s price and stock lists.

If default price and stock lists should not be used, extra price and stock lists can be added. To enable segment-specific stock and price lists, the lists must be created with a code.

• Currently, the code field appears only when ERP connection is selected in the UI, or it can be set via a PATCH request: Update Price List.

• The defined extra price and stock lists should be added to the catalog as extra lists.

• It takes time for these lists to sync with the Commerce system. They will only appear under the relevant segment's price and stock lists after synchronization.

• For products to be reflected under extra price and stock lists in Commerce, they must also be included in the default price and stock lists.

1. Currency Handling in Price Lists

If you want to create price lists for different currencies, you need to update the following settings in the sales channel’s dynamics settings:

• AVAILABLE_CURRENCIES

  
• DEFAULT_CURRENCY

  
• READ_CURRENCY_FROM_HEADER – Ensures currency is read from the FE request header.

  

How to Send Requests from the Frontend

When making requests from the front end, relevant values should be included either in the request header as key-value pairs or in cookies. More details and examples on setting currency in the FE can be found here.

Header-Based Configuration

All frontend requests that are dependent on user segmentation must include the following headers:

• Authorization: Bearer token for user authentication and authorization.

• Currency: Currency code (e.g., USD, EUR, TRY) to identify which price list to use.

Example Request:

GET /endpoint HTTP/1.1
Host: api.example.com
Authorization: Bearer <access_token>
Currency: USD

Sending Requests to Commerce

When making requests to Commerce, the correct header format should be followed to ensure the segmentation settings apply. Headers should include necessary values such as user segment information and currency to properly reflect the segmentation rules.

Required Headers for Commerce:

• Authorization: JWT or OAuth2 bearer token

• Currency: Active currency code

• User-Segment: The segment code assigned to the user (e.g., premium_users). If not provided, Commerce evaluates based on user ID and rule matching.

Example Request to Commerce:

GET /comm-endpoint HTTP/1.1
Host: api.example.com
Authorization: Bearer <access_token>
User-Segment: premium_users
Currency: EUR

Additional Notes

Category Tree Usage

• All segments use the same category tree.

• If certain products need to be hidden within specific segments, dynamic exclude can be used: Dynamic Exclude.