CustomerSavedSearch
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/2019-10/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/2019-10/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/2019-10/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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
}
}
]
}
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"
]
}
}
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 an existing Customer Saved Search
DELETE /admin/api/2019-10/customer_saved_searches/789629109.json
View Response
HTTP/1.1 200 OK
{
}
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/2020-01/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/2020-01/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/2020-01/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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
}
}
]
}
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"
]
}
}
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 an existing Customer Saved Search
DELETE /admin/api/2020-01/customer_saved_searches/789629109.json
View Response
HTTP/1.1 200 OK
{
}
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/2020-04/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/2020-04/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/2020-04/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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
}
}
]
}
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"
]
}
}
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 an existing Customer Saved Search
DELETE /admin/api/2020-04/customer_saved_searches/789629109.json
View Response
HTTP/1.1 200 OK
{
}
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/2020-07/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/2020-07/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/2020-07/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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
}
}
]
}
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"
]
}
}
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 an existing Customer Saved Search
DELETE /admin/api/2020-07/customer_saved_searches/789629109.json
View Response
HTTP/1.1 200 OK
{
}
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/2020-10/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/2020-10/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/2020-10/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/2020-10/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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
}
}
]
}
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"
]
}
}
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 an existing Customer Saved Search
DELETE /admin/api/2020-10/customer_saved_searches/789629109.json
View Response
HTTP/1.1 200 OK
{
}
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/2021-01/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/2021-01/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/2021-01/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/2021-01/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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
}
}
]
}
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"
]
}
}
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 an existing Customer Saved Search
DELETE /admin/api/2021-01/customer_saved_searches/789629109.json
View Response
HTTP/1.1 200 OK
{
}
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/2021-04/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/2021-04/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/2021-04/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/2021-04/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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
}
}
]
}
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"
]
}
}
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 an existing Customer Saved Search
DELETE /admin/api/2021-04/customer_saved_searches/789629109.json
View Response
HTTP/1.1 200 OK
{
}
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:
|
country |
Located in | Retrieves customers from a specified country. Valid values are the full name of any country in quotation marks. Example values:
|
customer_date |
Date created | Retrieve customers who were created within a set period of time. Valid values:
|
last_abandoned_order_date |
Abandoned an order | Retrieve customers who abandoned a cart within a set period of time. Valid values:
|
order_date |
Placed an order | Retrieve customers who placed an order within a set period of time. Valid values:
|
orders_count |
Orders placed | Filter customres by the number of orders they've placed with the store. Valid values:
|
state |
Account status | Filter customers by their customer account status. Valid values:
|
tag |
Tagged with | Filter customers by tag. Valid values are any existing customer tag, contained in quotation marks. Example values:
|
total_spent |
Money spent | Filter customers by the total amount that they have spent across all of their orders. Valid values:
|
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:
- GET /admin/api/unstable/customer_saved_searches.json Retrieves a list of customer saved searches
- GET /admin/api/unstable/customer_saved_searches/count.json Retrieves a count of all customer saved searches
- GET /admin/api/unstable/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
- GET /admin/api/unstable/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
- POST /admin/api/unstable/customer_saved_searches.json Creates a customer saved search
- PUT /admin/api/unstable/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
- DELETE /admin/api/unstable/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search
CustomerSavedSearch properties
created_at
read-only |
The date and time (ISO 8601 format) when the customer saved search was created. |
id
read-only |
A unique identifier for the customer saved search. |
name |
The name given by the shop owner to the customer saved search. |
query |
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 |
The date and time (ISO 8601 format) when the customer saved search was last modified. |
Endpoints
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"
}
]
}
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
}
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"
}
}
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