Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

CustomerSegmentTemplate

Requires the admin.customers.segmentation-templates.render target.

The CustomerSegmentTemplate component configures a segment template rendered in the Customers section of the Shopify admin. Use CustomerSegmentTemplate to define reusable segment queries that merchants can apply in the customer segment editor.

This component is required for all customer segmentation template extensions and provides a standardized structure for segment template cards.

Learn how to build a customer segment template extension.

Support

Targets (1)

Supported targets

admin.customers.segmentation-templates.render

Anchor to PropertiesProperties

Props for the CustomerSegmentTemplate component, which defines a reusable segment template that merchants can apply in the customer segment editor.

Anchor to description description string | string[] required: The localized description displayed below the title. Explains what customers the segment targets. Pass an array of strings to render multiple paragraphs.
Anchor to query query string required: The segment query displayed on the template card with syntax highlighting. This query isn't validated at render time.
Anchor to title title string required: The localized title displayed on the template card, such as "Customers with birthdays this month".
Anchor to createdOn createdOn string: The date the template was introduced, as an ISO 8601 string (such as '2025-01-15'). Templates created within the last month display a "New" badge.
Anchor to dependencies dependencies { standardMetafields?: "facts.birth_date"[]; customMetafields?: string[]; }: The metafields that the template's query depends on. Declaring dependencies lets the admin verify that the required metafield definitions exist before the merchant applies the template.
Anchor to queryToInsert queryToInsert string: The segment query inserted into the editor when the merchant applies the template. Defaults to query if not provided. This query isn't validated at render time.

Anchor to ExamplesExamples

Anchor to Create a repeat buyer segment templateCreate a repeat buyer segment template

Define a reusable customer segment for high-value repeat buyers. This example creates a CustomerSegmentTemplate with a query that filters by order count and total spend, plus a title, description, and createdOn date.

Create a repeat buyer segment template

import React from 'react';

import {reactExtension, CustomerSegmentTemplate} from '@shopify/ui-extensions-react/admin';

function App() {

return (

<CustomerSegmentTemplate

title="High-value repeat buyers"

description="Customers who have placed more than 5 orders with a total spend exceeding $500. Use this segment to target loyal customers for VIP promotions and early access campaigns."

query="number_of_orders > 5 AND amount_spent > 500"

createdOn={new Date('2024-06-01').toISOString()}

);

}

export default reactExtension(

'admin.customers.segmentation-templates.render',

() => <App />,

);

import {extension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';

export default extension(

'admin.customers.segmentation-templates.render',

(root, {i18n}) => {

const template = root.createComponent(CustomerSegmentTemplate, {

title: 'High-value repeat buyers',

description: 'Customers who have placed more than 5 orders with a total spend exceeding $500. Use this segment to target loyal customers for VIP promotions and early access campaigns.',

query: 'number_of_orders > 5 AND amount_spent > 500',

createdOn: new Date('2024-06-01').toISOString(),

});

root.appendChild(template);

);

React

import React from 'react';
import {reactExtension, CustomerSegmentTemplate} from '@shopify/ui-extensions-react/admin';

function App() {
  return (
    <CustomerSegmentTemplate
      title="High-value repeat buyers"
      description="Customers who have placed more than 5 orders with a total spend exceeding $500. Use this segment to target loyal customers for VIP promotions and early access campaigns."
      query="number_of_orders > 5 AND amount_spent > 500"
      createdOn={new Date('2024-06-01').toISOString()}
    />
  );
}

export default reactExtension(
  'admin.customers.segmentation-templates.render',
  () => <App />,
);

TS

import {extension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.customers.segmentation-templates.render',
  (root, {i18n}) => {
    const template = root.createComponent(CustomerSegmentTemplate, {
      title: 'High-value repeat buyers',
      description: 'Customers who have placed more than 5 orders with a total spend exceeding $500. Use this segment to target loyal customers for VIP promotions and early access campaigns.',
      query: 'number_of_orders > 5 AND amount_spent > 500',
      createdOn: new Date('2024-06-01').toISOString(),
    });

    root.appendChild(template);
  },
);

Anchor to Customize the inserted queryCustomize the inserted query

Use queryToInsert to provide a different query than what is displayed in the template preview. This example shows a complete query with a US region filter in the template card, but inserts a version with an empty region placeholder so merchants can customize the filter for their market.

Customize the inserted query

import React from 'react';

import {reactExtension, CustomerSegmentTemplate} from '@shopify/ui-extensions-react/admin';

function App() {

return (

<CustomerSegmentTemplate

title="Lapsed customers by region"

description={[

'Customers who have not placed an order in the last 90 days, filtered by geographic region.',

'The displayed query shows an example for US customers. When inserted into the editor, the region filter is left as a placeholder for merchants to customize.',

]}

query='days_since_last_order > 90 AND customer_country = "US"'

queryToInsert='days_since_last_order > 90 AND customer_country = ""'

createdOn={new Date('2024-08-15').toISOString()}

);

}

export default reactExtension(

'admin.customers.segmentation-templates.render',

() => <App />,

);

import {extension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';

export default extension(

'admin.customers.segmentation-templates.render',

(root, {i18n}) => {

const template = root.createComponent(CustomerSegmentTemplate, {

title: 'Lapsed customers by region',

description: [

'Customers who have not placed an order in the last 90 days, filtered by geographic region.',

'The displayed query shows an example for US customers. When inserted into the editor, the region filter is left as a placeholder for merchants to customize.',

query: 'days_since_last_order > 90 AND customer_country = "US"',

queryToInsert: 'days_since_last_order > 90 AND customer_country = ""',

createdOn: new Date('2024-08-15').toISOString(),

});

root.appendChild(template);

);

React

import React from 'react';
import {reactExtension, CustomerSegmentTemplate} from '@shopify/ui-extensions-react/admin';

function App() {
  return (
    <CustomerSegmentTemplate
      title="Lapsed customers by region"
      description={[
        'Customers who have not placed an order in the last 90 days, filtered by geographic region.',
        'The displayed query shows an example for US customers. When inserted into the editor, the region filter is left as a placeholder for merchants to customize.',
      ]}
      query='days_since_last_order > 90 AND customer_country = "US"'
      queryToInsert='days_since_last_order > 90 AND customer_country = ""'
      createdOn={new Date('2024-08-15').toISOString()}
    />
  );
}

export default reactExtension(
  'admin.customers.segmentation-templates.render',
  () => <App />,
);

TS

import {extension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.customers.segmentation-templates.render',
  (root, {i18n}) => {
    const template = root.createComponent(CustomerSegmentTemplate, {
      title: 'Lapsed customers by region',
      description: [
        'Customers who have not placed an order in the last 90 days, filtered by geographic region.',
        'The displayed query shows an example for US customers. When inserted into the editor, the region filter is left as a placeholder for merchants to customize.',
      ],
      query: 'days_since_last_order > 90 AND customer_country = "US"',
      queryToInsert: 'days_since_last_order > 90 AND customer_country = ""',
      createdOn: new Date('2024-08-15').toISOString(),
    });

    root.appendChild(template);
  },
);

Anchor to Declare metafield dependenciesDeclare metafield dependencies

Declare custom metafield dependencies using the dependencies prop so the segment editor knows which metafields your query references. This example filters customers by a loyalty.tier custom metafield, enabling the editor to validate the query and show relevant autocomplete suggestions.

Declare metafield dependencies

import React from 'react';

import {reactExtension, CustomerSegmentTemplate} from '@shopify/ui-extensions-react/admin';

function App() {

return (

<CustomerSegmentTemplate

title="Loyalty tier members"

description="Customers assigned to a specific loyalty tier through your app. This template uses a custom metafield to filter customers by their current membership level."

query='customer.metafields.loyalty.tier = "gold"'

dependencies={{

customMetafields: ['loyalty.tier'],

}}

createdOn={new Date('2024-10-01').toISOString()}

);

}

export default reactExtension(

'admin.customers.segmentation-templates.render',

() => <App />,

);

import {extension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';

export default extension(

'admin.customers.segmentation-templates.render',

(root, {i18n}) => {

const template = root.createComponent(CustomerSegmentTemplate, {

title: 'Loyalty tier members',

description: 'Customers assigned to a specific loyalty tier through your app. This template uses a custom metafield to filter customers by their current membership level.',

query: 'customer.metafields.loyalty.tier = "gold"',

dependencies: {

customMetafields: ['loyalty.tier'],

createdOn: new Date('2024-10-01').toISOString(),

});

root.appendChild(template);

);

React

import React from 'react';
import {reactExtension, CustomerSegmentTemplate} from '@shopify/ui-extensions-react/admin';

function App() {
  return (
    <CustomerSegmentTemplate
      title="Loyalty tier members"
      description="Customers assigned to a specific loyalty tier through your app. This template uses a custom metafield to filter customers by their current membership level."
      query='customer.metafields.loyalty.tier = "gold"'
      dependencies={{
        customMetafields: ['loyalty.tier'],
      }}
      createdOn={new Date('2024-10-01').toISOString()}
    />
  );
}

export default reactExtension(
  'admin.customers.segmentation-templates.render',
  () => <App />,
);

TS

import {extension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.customers.segmentation-templates.render',
  (root, {i18n}) => {
    const template = root.createComponent(CustomerSegmentTemplate, {
      title: 'Loyalty tier members',
      description: 'Customers assigned to a specific loyalty tier through your app. This template uses a custom metafield to filter customers by their current membership level.',
      query: 'customer.metafields.loyalty.tier = "gold"',
      dependencies: {
        customMetafields: ['loyalty.tier'],
      },
      createdOn: new Date('2024-10-01').toISOString(),
    });

    root.appendChild(template);
  },
);

Anchor to Best practicesBest practices

Write clear, localized titles and descriptions: Titles should briefly name the segment, while descriptions should explain what customers the segment targets. Both should be localized for the merchant's language.
Provide a valid segment query: Test the query in the segment editor before using it in a template to ensure it works correctly.

Anchor to LimitationsLimitations

The segment query is displayed with syntax highlighting in the template card, but it isn't validated at render time. Invalid queries will only fail when the merchant tries to apply the template.

Was this page helpful?