---
title: Manage customer segments
description: 'Learn how to create, retrieve, update, and delete customer segments.'
source_url:
  html: 'https://shopify.dev/docs/apps/build/marketing/customer-segments/manage'
  md: 'https://shopify.dev/docs/apps/build/marketing/customer-segments/manage.md'
---

# Manage customer segments

You can use the GraphQL Admin API to manage customer segments. This guide shows you how to create, retrieve, update, and delete customer segments.

***

## Requirements

* The store you're working with has [customer saved searches](https://shopify.dev/docs/api/admin-graphql/2022-01/queries/customersavedsearches) and [customers](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer).

- Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API.
- Your app has the `read_customers` and `write_customers` [access scopes](https://shopify.dev/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration).

***

## Step 1: Create a segment

To create a new segment, use the [`segmentCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/segmentCreate) mutation, and specify the name and query of the segment as arguments. In the following example, the query specifies customers that have subscribed to email marketing:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation {
  segmentCreate(name: "Email Subscribers", query: "email_subscription_status = 'SUBSCRIBED'") {
    segment {
      id
      name
      query
    }
    userErrors {
      message
      field
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segmentCreate": {
      "segment": {
        "id": "gid://shopify/Segment/SEGMENT_ID",
        "name": "Email Subscribers",
        "query": "email_subscription_status = 'SUBSCRIBED'"
      },
      "userErrors": []
    }
  }
}
```

***

## Step 2: Retrieve customer segments

You can retrieve a list of customer segments from a shop by querying [`segments`](https://shopify.dev/docs/api/admin-graphql/latest/queries/segments). In the following example, the response body returns the first segment, including the segment’s ID and name, and whether the segment is a default that was created by Shopify. The query also includes cursor and pagination information.

The query in the response body includes a combination of conditions on facts about the segment. In this case, the segment query specifies customers that have subscribed to email marketing.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query {
  segments(first: 1) {
    edges {
      cursor
      node {
        id
        name
        default
        query
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segments": {
      "edges": [
        {
          "cursor": "SEGMENT_CURSOR",
          "node": {
            "id": "gid://shopify/Segment/SEGMENT_ID",
            "name": "Email subscribers",
            "default": false,
            "query": "email_subscription_status = 'SUBSCRIBED'"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false
      }
    }
  }
}
```

### Query an individual segment

To query an individual segment, query the [`segment`](https://shopify.dev/docs/api/admin-graphql/latest/queries/segment) object and pass the segment ID as an argument:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query {
  segment(id: "gid://shopify/Segment/123") {
    id
    name
    query
  }
}
```

## JSON response

```json
{
  "data": {
    "segment": {
      "id": "gid://shopify/Segment/SEGMENT_ID",
      "name": "Email Subscribers",
      "query": "email_subscription_status = 'SUBSCRIBED'"
    }
  }
}
```

### Query a list of segment members

To retrieve a list of members associated with an individual segment, use the [`customerSegmentMembers`](https://shopify.dev/docs/api/admin-graphql/latest/queries/customerSegmentMembers) query, and pass in the segment attribute and conditions.

You can query a maximum of 250 segments. The maximum value that `first` and `last` arguments accept is `250`.

The following example shows how to retrieve a list of segment members that aren't subscribed to email communications. The first member of the segment is returned, including their customer ID, first name, last name, and default email address. Additional attribute statistics are also returned, including the member's total number of orders from the store and the average amount spent.

As of version 2023-01 of the GraphQL Admin API, the most complex queries might be processed asynchronously. You can [migrate your app to support async queries](https://shopify.dev/docs/apps/build/marketing/customer-segments/migrate-to-async-queries).

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query {
  customerSegmentMembers(first: 1, query: "email_subscription_status = 'NOT_SUBSCRIBED'") {
    totalCount
    statistics {
      attributeStatistics(attributeName: "amount_spent") {
        average
      }
    }
    edges {
      node {
        id
        firstName
        lastName
        defaultEmailAddress {
          emailAddress
        }
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "customerSegmentMembers": {
      "totalCount": 394,
      "statistics": {
        "attributeStatistics": {
          "average": 2807.767106598985
        }
      },
      "edges": [
        {
          "node": {
            "id": "gid://shopify/CustomerSegmentMember/CUSTOMER_ID",
            "firstName": "Alex",
            "lastName": "Doe",
            "defaultEmailAddress": {
              "emailAddress": "alexdoe@example.com"
            }
          }
        }
      ]
    }
  }
}
```

***

## Step 3: Retrieve segment filters

You can use the [`segmentFilters`](https://shopify.dev/docs/api/admin-graphql/latest/queries/segmentFilters) query to retrieve a list of filters [(attributes)](https://shopify.dev/docs/api/shopifyql/segment-query-language-reference#attributes) added to segment queries. In the following example, the first two segment filters are returned, including a human-readable, localized name for the filter and the filter name in ShopifyQL.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query {
  segmentFilters(first: 2) {
    edges {
      node {
        __typename
        # Shopify is supported in multiple languages. The `Accept-Language` header determines the translation returned by Shopify. If the header isn't supplied or the locale is unsupported, then the `localizedName` field returns values in English.
        localizedName
        queryName
        ... on EnumSegmentFilter {
          values(first: 2) {
            edges {
              node {
                localizedName
                queryName
              }
            }
          }
        }
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segmentFilters": {
      "edges": [
        {
          "node": {
            "__typename": "FloatSegmentFilter",
            "localizedName": "Amount Spent",
            "queryName": "amount_spent"
          }
        },
        {
          "node": {
            "__typename": "EnumSegmentFilter",
            "localizedName": "City",
            "queryName": "city",
            "values": {
              "edges": [
                {
                  "node": {
                    "localizedName": "New York City",
                    "queryName": "US-NY-NewYorkCity"
                  }
                },
                {
                  "node": {
                    "localizedName": "Los Angeles",
                    "queryName": "US-CA-LosAngeles"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}
```

### Query segment filter suggestions

You can use the [`segmentFilterSuggestions`](https://shopify.dev/docs/api/admin-graphql/latest/queries/segmentFilterSuggestions) query to retrieve a list of filter suggestions associated with a segment:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query {
  segmentFilterSuggestions(first: 1, search: "email") {
    edges {
      node {
        # Shopify is supported in multiple languages. The `Accept-Language` header determines the translation returned by Shopify. If the header isn't supplied or the locale is unsupported, then the `localizedName` field returns values in English.
        localizedName
        queryName
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segmentFilterSuggestions": {
      "edges": [
        {
          "node": {
            "localizedName": "Email Domain",
            "queryName": "email_domain"
          }
        }
      ]
    }
  }
}
```

### Query segment value suggestions

You can use the [`segmentValueSuggestions`](https://shopify.dev/docs/api/admin-graphql/latest/queries/segmentValueSuggestions) query to retrieve a list of value suggestions associated with a segment:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query {
  segmentValueSuggestions(first: 2, filterQueryName: "email_subscription_status", search: "subs") {
    edges {
      node {
        # Shopify is supported in multiple languages. The `Accept-Language` header determines the translation returned by Shopify. If the header isn't supplied or the locale is unsupported, then the `localizedName` field returns values in English.
        localizedValue
        queryName
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segmentValueSuggestions": {
      "edges": [
        {
          "node": {
            "localizedValue": "Subscribed",
            "queryName": "SUBSCRIBED"
          }
        },
        {
          "node": {
            "localizedValue": "Not subscribed",
            "queryName": "NOT_SUBSCRIBED"
          }
        }
      ]
    }
  }
}
```

***

## Step 4: Apply a discount to a customer segment

After you've retrieved a list of segments from the store, you can use a [code discount](https://shopify.dev/docs/apps/build/discounts#related-mutations-and-queries) mutation to specify which `segmentId` you want to apply a discount to.

The following example shows how to use the [`discountCodeBasicCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/discountcodebasiccreate) mutation to apply a 10%-off all items discount, named "Discount", to two customer segments:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL Mutation

```graphql
mutation createBasicDiscount {
  discountCodeBasicCreate(basicCodeDiscount: {
    title: "Discount"
    code: "Discount"
    customerGets: {
      value: {
        percentage: 0.1
      }
      items: {
        all: true
      }
    }
    customerSelection: {
      all: false
      customerSegments: {
        add: [
          "gid:\/\/shopify\/Segment\/429383024662",
          "gid:\/\/shopify\/Segment\/429383057430",
        ]
      }
    }
    startsAt: "20200202T020202"
  }) {
    codeDiscountNode {
      id
      codeDiscount {
        __typename
        ... on DiscountCodeBasic {
          title
          customerSelection {
            ... on DiscountCustomerSegments {
              segments {
                id
                query
              }
            }
          }
        }
      }
    }
    userErrors {
      code
      field
      message
      extraInfo
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segments": {
      "edges": [
        {
          "node": {
            "id": "gid:\/\/shopify\/Segment\/429383024662"
          }
        },
        {
          "node": {
            "id": "gid:\/\/shopify\/Segment\/429383057430"
          }
        },
        {
          "node": {
            "id": "gid:\/\/shopify\/Segment\/429383090198"
          }
        },
        {
          "node": {
            "id": "gid:\/\/shopify\/Segment\/429383122966"
          }
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 252,
      "actualQueryCost": 6,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 994,
        "restoreRate": 50.0
      }
    }
  }
}
```

***

## Step 5: Update a segment

To update an existing segment, use the [`segmentUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/segmentUpdate) mutation, and specify the `id` of the `segment` you that you want to update:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation {
  segmentUpdate(id: "gid://shopify/Segment/SEGMENT_ID", name: "Updated Segment Name") {
    segment {
      id
      name
      query
    }
    userErrors {
      message
      field
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segmentUpdate": {
      "segment": {
        "id": "gid://shopify/Segment/SEGMENT_ID",
        "name": "Updated Segment Name",
        "query": "email_subscription_status = 'SUBSCRIBED'"
      },
      "userErrors": []
    }
  }
}
```

***

## Step 6 (Optional): Delete a segment

To permanently remove a segment from a shop, use the [`segmentDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/segmentDelete) mutation, and specify the `id` of the `segment` that you want to delete:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation {
  segmentDelete(id: "gid://shopify/Segment/456") {
    deletedSegmentId
    userErrors {
      field
      message
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "segmentDelete": {
      "deletedSegmentId": "gid://shopify/Segment/456",
      "userErrors": []
    }
  }
}
```

***

## Next steps

* Migrate from [saved searches to customer segments](https://shopify.dev/docs/apps/build/marketing/customer-segments/migrate-saved-searches).

***