Using Customer Segments

Once a segment is created, you can use it as a condition in promotions and rules, retrieve which customers belong to it, and check which segments a given customer is part of.

Using Segments in Promotions

When configuring a promotion, you can assign one or more segments as targeting conditions. A segment can be set as an allowlist (include) – only customers in this segment see and can apply the promotion – or as a blocklist (exclude), which hides the promotion from customers in that segment.

You can combine include and exclude conditions on the same promotion. A customer must satisfy all allowlist conditions and none of the blocklist conditions for the promotion to be visible to them.

Segment membership is evaluated in real time at the point of promotion validation, so customers who join or leave a qualifying group are immediately reflected without any manual sync.

Customer segments can be applied to the following promotion types in the SCAYLE Panel:

Advanced Promotions
Automatic Discounts
Buy X Get Y
Combo Deals
Flash Sales
Tiered Discounts
Promo Codes

Customer segment selector inside a promotion creating page — Customer segment selector displays the available segments to select

In the promotion creation or edit form, find the Customer segments section. Choose between:

All customer segments: the promotion applies to every customer regardless of segment (default).
Selected customer segments: restrict the promotion to specific segments.

When Selected customer segments is chosen, two targeting modes become available:

Allowlist: only customers who belong to the selected segments are eligible for the promotion.
Blocklist: customers who belong to the selected segments are excluded from the promotion.

Use the search field to find and add segments by name. Selected segments appear in the Selected customer segments list below, where they can also be removed individually.

Storefront API Behavior

The X-Customer-Token is the customer's OAuth2 access token, issued by the Authentication API.

When using the Storefront API, requests are automatically scoped to the customer segments when an X-Customer-Token is provided in the header. The Storefront API will only return or apply promotions that the user is eligible for.

This applies to requests to these endpoints:

/v1/promotions
/v1/baskets

You can find more detailed information on how to structure your request in the API specifications for the /v1/promotions and /v1/baskets endpoints.

On the storefront, segment-based promotions are only visible to logged-in customers whose profile matches the configured criteria. Guest users and unauthenticated sessions will not see segment-restricted promotions.

For server-side rendered pages, segment-based promotions are not included in the initial page load. They are fetched client-side once the customer session is available. Build your storefront integration to handle this two-step load to ensure segment-based promotions appear correctly for logged-in users.

We recommend fetching applicable promotions client-side after session establishment, and re-fetching after any basket action that could affect promotion eligibility.

For additional information on how to use promotions scoped to customer segments in the Storefront Application, see the Storefront Application guide on Promotions and Campaigns.

Filtering Rules

When a customer is identified, each promotion is evaluated as follows:

A promotion with a segment Allowlist is returned only if the customer belongs to at least one of the listed segments.
A promotion with a segment Blocklist is excluded if the customer belongs to any of the listed segments.
A promotion with no segment configuration is always returned.

List Segment-Aware Promotions

Call /v1/promotions with an X-Customer-Token to receive only the promotions applicable to the customer's segments.

Response

Example: Promotions Change After Login

Suppose a merchant has configured a promotion VIP Members -20% with a segment allow-list, so it is only valid for customers in the VIP Members segment. A regular Summer Sale promotion has no segment restriction.

Guest request (no token)

Segment-gated promotions are suppressed, so only Summer Sale is returned.

{% tabs %}

{% tab title="TypeScript" %}

{% endtab %}

{% tab title="cURL" %}

{% endtab %}

{% endtabs %}

Response

The customer belongs to the VIP Members segment, so the segment-gated promotion is now included alongside the public one.

{% tabs %}

{% tab title="TypeScript" %}

{% endtab %}

{% tab title="cURL" %}

{% endtab %}

{% endtabs %}

Response

Applicable Promotions on the Basket

When fetching a basket with ?with=applicablePromotions and a customer token, the returned promotions respect the customer's segment membership. The same applies across the basket lifecycle: adding, updating, and removing items, and applying promotions.

const { basket } = await client.basket.get("7f2c4a", {
  with: { applicablePromotions: true },
  customerToken: "{{customerToken}}",
});

Response

Applicable Promotions by Code

POST /v1/baskets/{basketId}/promotion-code returns the applicable promotions for a submitted code. When a customer token is supplied, only promotions valid for the customer's segments are returned.

Response