API version: unstable
API version: 2021-04 Release candidate
API version: 2021-01 Latest
API version: 2020-10
API version: 2020-07
API version: 2020-04
API version: 2020-01 Unsupported
API version: 2019-10 Unsupported

CustomerSavedSearch

Version 2019-10

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2019-10/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/2019-10/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/2019-10/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/2019-10/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2019-10/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/2019-10/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/2019-10/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/2019-10/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2021-02-05T20:59:20-05:00",
      "updated_at": "2021-02-05T21:14:59-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "addresses": [
        {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ],
      "accepts_marketing_updated_at": "2021-02-05T21:14:59-05:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}
POST /admin/api/2019-10/customer_saved_searches.json
Creates a customer saved search.

Create a customer saved search

POST /admin/api/2019-10/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136102,
    "name": "Spent more than $50",
    "created_at": "2021-02-05T21:15:09-05:00",
    "updated_at": "2021-02-05T21:15:09-05:00",
    "query": "total_spent:>50"
  }
}

Create a customer saved search with multiple terms

POST /admin/api/2019-10/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50 and after 2013",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136103,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2021-02-05T21:15:12-05:00",
    "updated_at": "2021-02-05T21:15:12-05:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Creating a customer saved search without a name fails and returns an error

POST /admin/api/2019-10/customer_saved_searches.json
{
  "customer_saved_search": {
    "body": "foobar"
  }
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json
Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2019-10/customer_saved_searches/789629109.json
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-02-05T21:14:28-05:00",
    "query": "accepts_marketing:1"
  }
}
DELETE /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json
Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2019-10/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2020-01

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2020-01/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/2020-01/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/2020-01/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/2020-01/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-01/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/2020-01/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/2020-01/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/2020-01/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2021-02-05T20:59:20-05:00",
      "updated_at": "2021-02-05T21:14:59-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "addresses": [
        {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ],
      "accepts_marketing_updated_at": "2021-02-05T21:14:59-05:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}
POST /admin/api/2020-01/customer_saved_searches.json
Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-01/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136102,
    "name": "Spent more than $50",
    "created_at": "2021-02-05T21:15:09-05:00",
    "updated_at": "2021-02-05T21:15:09-05:00",
    "query": "total_spent:>50"
  }
}

Create a customer saved search with multiple terms

POST /admin/api/2020-01/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50 and after 2013",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136103,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2021-02-05T21:15:12-05:00",
    "updated_at": "2021-02-05T21:15:12-05:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Creating a customer saved search without a name fails and returns an error

POST /admin/api/2020-01/customer_saved_searches.json
{
  "customer_saved_search": {
    "body": "foobar"
  }
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json
Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-01/customer_saved_searches/789629109.json
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-02-05T21:14:28-05:00",
    "query": "accepts_marketing:1"
  }
}
DELETE /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json
Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-01/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2020-04

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2020-04/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/2020-04/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/2020-04/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/2020-04/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-04/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/2020-04/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/2020-04/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/2020-04/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2021-02-05T20:59:20-05:00",
      "updated_at": "2021-02-05T21:14:59-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "addresses": [
        {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ],
      "accepts_marketing_updated_at": "2021-02-05T21:14:59-05:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}
POST /admin/api/2020-04/customer_saved_searches.json
Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-04/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136102,
    "name": "Spent more than $50",
    "created_at": "2021-02-05T21:15:09-05:00",
    "updated_at": "2021-02-05T21:15:09-05:00",
    "query": "total_spent:>50"
  }
}

Create a customer saved search with multiple terms

POST /admin/api/2020-04/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50 and after 2013",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136103,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2021-02-05T21:15:12-05:00",
    "updated_at": "2021-02-05T21:15:12-05:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Creating a customer saved search without a name fails and returns an error

POST /admin/api/2020-04/customer_saved_searches.json
{
  "customer_saved_search": {
    "body": "foobar"
  }
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json
Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-04/customer_saved_searches/789629109.json
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-02-05T21:14:28-05:00",
    "query": "accepts_marketing:1"
  }
}
DELETE /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json
Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-04/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2020-07

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2020-07/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/2020-07/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/2020-07/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/2020-07/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-07/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/2020-07/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/2020-07/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/2020-07/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2021-02-05T20:59:20-05:00",
      "updated_at": "2021-02-05T21:14:59-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "addresses": [
        {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ],
      "accepts_marketing_updated_at": "2021-02-05T21:14:59-05:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}
POST /admin/api/2020-07/customer_saved_searches.json
Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-07/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136102,
    "name": "Spent more than $50",
    "created_at": "2021-02-05T21:15:09-05:00",
    "updated_at": "2021-02-05T21:15:09-05:00",
    "query": "total_spent:>50"
  }
}

Create a customer saved search with multiple terms

POST /admin/api/2020-07/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50 and after 2013",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136103,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2021-02-05T21:15:12-05:00",
    "updated_at": "2021-02-05T21:15:12-05:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Creating a customer saved search without a name fails and returns an error

POST /admin/api/2020-07/customer_saved_searches.json
{
  "customer_saved_search": {
    "body": "foobar"
  }
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json
Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-07/customer_saved_searches/789629109.json
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-02-05T21:14:28-05:00",
    "query": "accepts_marketing:1"
  }
}
DELETE /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json
Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-07/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2020-10

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2020-10/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/2020-10/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/2020-10/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/2020-10/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-10/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/2020-10/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/2020-10/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/2020-10/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2021-02-05T20:59:20-05:00",
      "updated_at": "2021-02-05T21:14:59-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "addresses": [
        {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ],
      "accepts_marketing_updated_at": "2021-02-05T21:14:59-05:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}
POST /admin/api/2020-10/customer_saved_searches.json
Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-10/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136102,
    "name": "Spent more than $50",
    "created_at": "2021-02-05T21:15:09-05:00",
    "updated_at": "2021-02-05T21:15:09-05:00",
    "query": "total_spent:>50"
  }
}

Create a customer saved search with multiple terms

POST /admin/api/2020-10/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50 and after 2013",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136103,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2021-02-05T21:15:12-05:00",
    "updated_at": "2021-02-05T21:15:12-05:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Creating a customer saved search without a name fails and returns an error

POST /admin/api/2020-10/customer_saved_searches.json
{
  "customer_saved_search": {
    "body": "foobar"
  }
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}.json
Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-10/customer_saved_searches/789629109.json
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-02-05T21:14:28-05:00",
    "query": "accepts_marketing:1"
  }
}
DELETE /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}.json
Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-10/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2021-01 (Latest)

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2021-01/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/2021-01/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/2021-01/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/2021-01/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2021-01/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/2021-01/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/2021-01/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/2021-01/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2021-02-05T20:59:20-05:00",
      "updated_at": "2021-02-05T21:14:59-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "addresses": [
        {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ],
      "accepts_marketing_updated_at": "2021-02-05T21:14:59-05:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}
POST /admin/api/2021-01/customer_saved_searches.json
Creates a customer saved search.

Create a customer saved search

POST /admin/api/2021-01/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136102,
    "name": "Spent more than $50",
    "created_at": "2021-02-05T21:15:09-05:00",
    "updated_at": "2021-02-05T21:15:09-05:00",
    "query": "total_spent:>50"
  }
}

Create a customer saved search with multiple terms

POST /admin/api/2021-01/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50 and after 2013",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136103,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2021-02-05T21:15:12-05:00",
    "updated_at": "2021-02-05T21:15:12-05:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Creating a customer saved search without a name fails and returns an error

POST /admin/api/2021-01/customer_saved_searches.json
{
  "customer_saved_search": {
    "body": "foobar"
  }
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}.json
Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2021-01/customer_saved_searches/789629109.json
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-02-05T21:14:28-05:00",
    "query": "accepts_marketing:1"
  }
}
DELETE /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}.json
Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2021-01/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2021-04 (Release candidate)

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2021-04/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/2021-04/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/2021-04/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/2021-04/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2021-04/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/2021-04/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/2021-04/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/2021-04/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2021-02-05T20:59:20-05:00",
      "updated_at": "2021-02-05T21:14:59-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "addresses": [
        {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ],
      "accepts_marketing_updated_at": "2021-02-05T21:14:59-05:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}
POST /admin/api/2021-04/customer_saved_searches.json
Creates a customer saved search.

Create a customer saved search

POST /admin/api/2021-04/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136102,
    "name": "Spent more than $50",
    "created_at": "2021-02-05T21:15:09-05:00",
    "updated_at": "2021-02-05T21:15:09-05:00",
    "query": "total_spent:>50"
  }
}

Create a customer saved search with multiple terms

POST /admin/api/2021-04/customer_saved_searches.json
{
  "customer_saved_search": {
    "name": "Spent more than $50 and after 2013",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136103,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2021-02-05T21:15:12-05:00",
    "updated_at": "2021-02-05T21:15:12-05:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Creating a customer saved search without a name fails and returns an error

POST /admin/api/2021-04/customer_saved_searches.json
{
  "customer_saved_search": {
    "body": "foobar"
  }
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}.json
Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2021-04/customer_saved_searches/789629109.json
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-02-05T21:14:28-05:00",
    "query": "accepts_marketing:1"
  }
}
DELETE /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}.json
Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2021-04/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
}
Version unstable

A customer saved search is a search query that represents a group of customers defined by the shop owner.

In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When results are returned, the shop owner can save the search and give it a name. After the customer saved search is created, the shop owner can select it at a later date to see a list of customers that match the query.

Customer saved search queries

Use the following table to construct customer search queries:

API value Admin UI value Description
accepts_marketing Accepts marketing Filters customers by whether they accept email marketing. Valid values:
  • 0: Return customers who don't accept email marketing.
  • 1: Return customers who do accept email marketing.
country Located in Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
  • \"United States\": Return only customers from the United States. The double quotes have been escaped.
  • 'Canada': Return only customers from Canada.
customer_date Date created Retrieve customers who were created within a set period of time. Valid values:
  • past_week: Return customers who were created in the last week.
  • past_month: Return customers who were created in the last month.
  • last_3_months: Return customers who were created in the last 3 months.
  • past_quarter: Return customers who were created in the last quarter.
  • past_year: Return customers who were created in the last year.
  • yyyy-m-d: Return customers who were created on a set date.
  • >yyyy-m-d: Return customers who were created after a set date.
  • <yyyy-m-d: Return customers who were created before a set date.
last_abandoned_order_date Abandoned an order Retrieve customers who abandoned a cart within a set period of time. Valid values:
  • last_week: Return customers who abandoned a cart in the last week.
  • last_month: Return customers who abandoned a cart in the last month.
order_date Placed an order Retrieve customers who placed an order within a set period of time. Valid values:
  • last_week: Return customers who placed an order in the last week.
  • last_month: Return customers who placed an order in the last month.
  • last_3_months: Return customers who placed an order in the last 3 months.
  • last_year: Return customers who placed an order in the last year.
  • >yyyy-m-d: Return customers who placed an order after the specified date.
  • <yyyy-m-d: Return customers who placed an order before the specified date.
orders_count Orders placed Filter customres by the number of orders they've placed with the store. Valid values:
  • >number_of_orders: Return customers who have placed fewer than the specified number of orders.
  • <number_of_orders: Return customers who have placed more than the specified number of orders.
  • number_of_orders: Return customers who have placed the specified number of orders.
state Account status Filter customers by their customer account status. Valid values:
  • declined: Return customers who have been invited to create an account but declined.
  • disabled: Return customers whose account is disabled.
  • enabled: Return customers who have a customer account.
  • invited: Return customers who have been invited to create an account.
tag Tagged with Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
  • \"Big spender\": Return customers who have the tag Big spender. The double quotation marks have been escaped.
  • 'Favorite': Return customers who have the tag Favorite.
total_spent Money spent Filter customers by the total amount that they have spent across all of their orders. Valid values:
  • >money_amount: Return customers who have spent less than the specified amount of money.
  • <money_amount: Return customers who have spent more than the specified amount of money.
  • money_amount: Return customers who have spent the specified amount of money.

What you can do with CustomerSavedSearch

The Shopify API lets you do the following with the CustomerSavedSearch resource. More detailed versions of these general actions may be available:

CustomerSavedSearch properties

created_at
read-only 
"created_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was created.
id
read-only 
"id": 789629109

A unique identifier for the customer saved search.
name 
"name": "Accepts Marketing"

The name given by the shop owner to the customer saved search.
query 
"query": "accepts_marketing:1"

The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at
read-only 
"updated_at": "2012-08-17T10:01:46-04:00"

The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/unstable/customer_saved_searches.json
Retrieves a list of customer saved searches. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customer saved searches for a shop

GET /admin/api/unstable/customer_saved_searches.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

Retrieve all customer saved searches for a shop after a specified ID

GET /admin/api/unstable/customer_saved_searches.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2021-01-29T20:59:20-05:00",
      "updated_at": "2021-01-29T20:59:20-05:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET /admin/api/unstable/customer_saved_searches/count.json
Retrieves a count of all customer saved searches.
since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/unstable/customer_saved_searches/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all customer saved searches after a specified ID

GET /admin/api/unstable/customer_saved_searches/count.json?since_id=20610973
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
GET /admin/api/unstable/customer_saved_searches/{customer_saved_search_id}.json
Retrieves a single customer saved search.
fields

Show only certain fields, specified by a comma-separated list of field names.

Get one customer saved search by ID

GET /admin/api/unstable/customer_saved_searches/789629109.json
View Response 
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2021-01-29T20:59:20-05:00",
    "updated_at": "2021-01-29T20:59:20-05:00",
    "query": "accepts_marketing:1"
  }
}
GET /admin/api/unstable/customer_saved_searches/{customer_saved_search_id}/customers.json
Retrieves all customers returned by a customer saved search.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve customers who match the query for the specified customer saved search

GET /admin/api/unstable/customer_saved_searches/789629109/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551</