---
title: Migrate to async segmentation queries
description: >-
  Learn how to migrate your app to support asynchronous customer segment
  queries.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries
  md: >-
    https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md
---

ExpandOn this page

* [Step 1: Retrieve a list of segment members](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-1-retrieve-a-list-of-segment-members)
* [Step 2: Request an asynchronous query](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-2-request-an-asynchronous-query)
* [Step 3: Check the request status](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-3-check-the-request-status)
* [Step 4: Retrieve the list of customer segment members](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-4-retrieve-the-list-of-customer-segment-members)

# Migrate to async segmentation queries

Version 2023-01 of the GraphQL Admin API introduces support for asynchronous queries in [`customersSegmentMembers`](https://shopify.dev/docs/api/admin-graphql/latest/queries/customerSegmentMembers). While most queries will continue to resolve synchronously, some queries could be processed asynchronously based on query complexity and the amount of shop data. Building proper asynchronous query handling provides a better user experience for complex queries.

This guide shows you how to migrate your app to support asynchronous customer segment queries.

Caution

Asynchronous queries in the Segmentation API represent a breaking change. As Shopify introduces more complex filters, some queries could be returned async. Your app should properly handle `customerSegmentMembers` error codes and request that the query is processed async with the [`customerSegmentMembersQueryCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSegmentMembersQueryCreate) mutation.

***

## Step 1: Retrieve a list of segment members

If a query to [`customersSegmentMembers`](https://shopify.dev/docs/api/admin-graphql/latest/queries/customerSegmentMembers) must be processed asynchronously, then the API returns a `USE_CUSTOMER_SEGMENT_MEMBERS_QUERY_CREATE_MUTATION` error.

The API can return async queries for unsaved and saved segments (`query` and `segmentId` GraphQL parameters respectively).

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

## GraphQL query

```graphql
query {
  customerSegmentMembers(first: 250, query: "products_purchased(tag: 'Summer') = true") {
    edges {
      node {
        id
      }
    }
  }
}
```

## JSON response

```json
{
  "data": null,
  "errors": [
    {
      "message": "This query can only be run async. Create an async query using the `customerSegmentMembersQueryCreate` mutation.",
      "extensions": {
        "code": "USE_CUSTOMER_SEGMENT_MEMBERS_QUERY_CREATE_MUTATION"
      }
    }
  ]
}
```

***

## Step 2: Request an asynchronous query

You can use the [`customerSegmentMembersQueryCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSegmentMembersQueryCreate) mutation to process your request asynchronously. Provide the `query` or `segmentId` as part of the `input`. You can optionally include the `sortKey` and `reverse` parameters.

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

## GraphQL mutation

```graphql
mutation {
  customerSegmentMembersQueryCreate(input: {query: "products_purchased(tag: 'Summer') = true"}) {
    customerSegmentMembersQuery {
      id
      done
      currentCount
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "customerSegmentMembersQueryCreate": {
      "customerSegmentMembersQuery": {
        "id": "gid://shopify/CustomerSegmentMembersQuery/2ed6f10e-69d4-11ed-a420-422b7f2d5e38",
        "done": false,
        "currentCount": 0
      },
      "userErrors": []
    }
  }
}
```

The response contains a `id`, which is a unique identifier for the request, `done`, which represents the query's status, and a `currentCount` of the number of segment members in your saved or unsaved segment.

***

## Step 3: Check the request status

Most async queries should revolve within five seconds but some queries might take one to two minutes or even longer depending on query complexity and amount of shop data.

You can check the status of your async request using its unique identifier. The response contains information about the query status and current count.

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

## GraphQL query

```graphql
query {
  customerSegmentMembersQuery(id: "gid://shopify/CustomerSegmentMembersQuery/9b176cdb-66b2-11ed-9a62-dab485c0c64b") {
    id
    ... on CustomerSegmentMembersQuery {
      currentCount
      done
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "customerSegmentMembersQuery": {
      "id": "gid://shopify/CustomerSegmentMembersQuery/0a9212fb-675c-11ed-8a67-422b7f2d5e38",
      "currentCount": 234,
      "done": false
    }
  }
}
```

Alternatively, you can try to retrieve the list of customer segment members using the `queryId` parameter. If the async query is still running, then the `QUERY_NOT_COMPLETE` error code is returned.

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

## GraphQL query

```graphql
query {
  customerSegmentMembers(first: 250, queryId: "gid://shopify/CustomerSegmentMembersQuery/0a9212fb-675c-11ed-8a67-422b7f2d5e38") {
    edges {
      node {
        id
      }
    }
  }
}
```

## JSON response

```json
{
  "data": null,
  "errors": [
    {
      "message": "This async query is still in progress.",
      "extensions": {
        "code": "QUERY_NOT_COMPLETE"
      }
    }
  ]
}
```

***

## Step 4: Retrieve the list of customer segment members

After the async query completes, you can retrieve a list of segment members by querying [`customersSegmentMembers`](https://shopify.dev/docs/api/admin-graphql/latest/queries/customerSegmentMembers) and passing in the `queryID` parameter.

Note

Note: Async queries won't update as your customer base changes. To retrieve the latest results, you need to re-run the query.

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

## GraphQL query

```graphql
query {
  customerSegmentMembers(first: 250, queryId: "gid://shopify/CustomerSegmentMembersQuery/0a9212fb-675c-11ed-8a67-422b7f2d5e38") {
    edges {
      node {
        id
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "customerSegmentMembers": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/CustomerSegmentMember/CUSTOMER_ID",
          }
        }
      ]
    }
  }
}
```

***

* [Step 1: Retrieve a list of segment members](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-1-retrieve-a-list-of-segment-members)
* [Step 2: Request an asynchronous query](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-2-request-an-asynchronous-query)
* [Step 3: Check the request status](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-3-check-the-request-status)
* [Step 4: Retrieve the list of customer segment members](https://shopify.dev/docs/apps/build/marketing-analytics/customer-segments/migrate-to-async-queries.md#step-4-retrieve-the-list-of-customer-segment-members)