# CustomerSavedSearch
A customer saved search is a search query that represents a group of customers defined by the shop owner.
{{ '/api/reference/customer-saved-search.png' | image }}In the Shopify admin, the shop owner searches for customers by entering a query and applying one or more filters. When the search 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.
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:
|
page
parameter will return an error. To learn more, see Make paginated requests to the REST Admin API.
### Endpoint
/admin/api/#{api_version}/customer_saved_searches.json (GET)
### Parameters
* api_version (required):
* fields: Show only certain fields, specified by a comma-separated list of field names.
* limit: The maximum number of results to show.
* since_id: Restrict results to after the specified ID.
### Responses
#### 200
Retrieves a list of customer saved searches
Examples:
##### Retrieve all customer saved searches for a shop
Request:
```
GET /admin/api/2019-07/customer_saved_searches.json
```
Response:
```
HTTP/1.1 200 OK
{"customer_saved_searches":[{"id":789629109,"name":"Accepts Marketing","created_at":"2023-06-07T14:27:29-04:00","updated_at":"2023-06-07T14:27:29-04:00","query":"accepts_marketing:1"},{"id":20610973,"name":"Canadian Snowboarders","created_at":"2023-06-07T14:27:29-04:00","updated_at":"2023-06-07T14:27:29-04:00","query":"country:Canada"},{"id":669439218,"name":"Premier Customers","created_at":"2023-06-07T14:27:29-04:00","updated_at":"2023-06-07T14:27:29-04:00","query":"John Smith orders_count:>10 total_spent:>100.00"}]}
```
##### Retrieve all customer saved searches for a shop after a specified ID
Request:
```
GET /admin/api/2019-07/customer_saved_searches.json
```
Response:
```
HTTP/1.1 200 OK
{"customer_saved_searches":[{"id":669439218,"name":"Premier Customers","created_at":"2023-06-07T14:27:29-04:00","updated_at":"2023-06-07T14:27:29-04:00","query":"John Smith orders_count:>10 total_spent:>100.00"},{"id":789629109,"name":"Accepts Marketing","created_at":"2023-06-07T14:27:29-04:00","updated_at":"2023-06-07T14:27:29-04:00","query":"accepts_marketing:1"}]}
```
## Creates a customer saved search
Creates a customer saved search.
### Endpoint
/admin/api/#{api_version}/customer_saved_searches.json (POST)
### Parameters
* api_version (required):
### Responses
#### 201
Creates a customer saved search
Examples:
##### Create a customer saved search
Request:
```
POST /admin/api/unstable/customer_saved_searches.json
{"customer_saved_search":{"name":"Spent more than $50","query":"total_spent:>50"}}
```
Response:
```
HTTP/1.1 201 Created
{"customer_saved_search":{"id":1068136103,"name":"Spent more than $50","created_at":"2023-06-14T14:30:44-04:00","updated_at":"2023-06-14T14:30:44-04:00","query":"total_spent:>50"}}
```
##### Create a customer saved search with multiple terms
Request:
```
POST /admin/api/unstable/customer_saved_searches.json
{"customer_saved_search":{"name":"Spent more than $50 and after 2013","query":"total_spent:>50 order_date:>=2013-01-01"}}
```
Response:
```
HTTP/1.1 201 Created
{"customer_saved_search":{"id":1068136102,"name":"Spent more than $50 and after 2013","created_at":"2023-06-14T14:30:33-04:00","updated_at":"2023-06-14T14:30:33-04:00","query":"total_spent:>50 order_date:>=2013-01-01"}}
```
#### 422
Creates a customer saved search
Examples:
##### Creating a customer saved search without a name fails and returns an error
Request:
```
POST /admin/api/unstable/customer_saved_searches.json
{"customer_saved_search":{"body":"foobar"}}
```
Response:
```
HTTP/1.1 422 Unprocessable Entity
{"errors":{"name":["can't be blank"],"search_terms":["can't be blank"]}}
```
## Retrieves a count of all customer saved searches
Retrieves a count of all customer saved searches.
### Endpoint
/admin/api/#{api_version}/customer_saved_searches/count.json (GET)
### Parameters
* api_version (required):
* since_id: Restrict results to after the specified ID
### Responses
#### 200
Retrieves a count of all customer saved searches
Examples:
##### Retrieve a count all customer saved searches
Request:
```
GET /admin/api/unstable/customer_saved_searches/count.json
```
Response:
```
HTTP/1.1 200 OK
{"count":3}
```
##### Retrieve a count of all customer saved searches after a specified ID
Request:
```
GET /admin/api/unstable/customer_saved_searches/count.json
```
Response:
```
HTTP/1.1 200 OK
{"count":2}
```
## Retrieves a single customer saved search
Retrieves a single customer saved search.
### Endpoint
/admin/api/#{api_version}/customer_saved_searches/{customer_saved_search_id}.json (GET)
### Parameters
* api_version (required):
* customer_saved_search_id (required):
* fields: Show only certain fields, specified by a comma-separated list of field names.
### Responses
#### 200
Retrieves a single customer saved search
Examples:
##### Get one customer saved search by ID
Request:
```
GET /admin/api/unstable/customer_saved_searches/789629109.json
```
Response:
```
HTTP/1.1 200 OK
{"customer_saved_search":{"id":789629109,"name":"Accepts Marketing","created_at":"2023-06-07T14:27:29-04:00","updated_at":"2023-06-07T14:27:29-04:00","query":"accepts_marketing:1"}}
```
## Updates a customer saved search
Updates a customer saved search.
### Endpoint
/admin/api/#{api_version}/customer_saved_searches/{customer_saved_search_id}.json (PUT)
### Parameters
* api_version (required):
* customer_saved_search_id (required):
### Responses
#### 200
Updates a customer saved search
Examples:
##### Update an existing customer saved search
Request:
```
PUT /admin/api/unstable/customer_saved_searches/789629109.json
{"customer_saved_search":{"id":789629109,"name":"This Name Has Been Changed"}}
```
Response:
```
HTTP/1.1 200 OK
{"customer_saved_search":{"name":"This Name Has Been Changed","id":789629109,"created_at":"2023-06-07T14:27:29-04:00","updated_at":"2023-06-14T14:30:30-04:00","query":"accepts_marketing:1"}}
```
## Deletes a customer saved search
Deletes a customer saved search.
### Endpoint
/admin/api/#{api_version}/customer_saved_searches/{customer_saved_search_id}.json (DELETE)
### Parameters
* api_version (required):
* customer_saved_search_id (required):
### Responses
#### 200
Deletes a customer saved search
Examples:
##### Delete an existing Customer Saved Search
Request:
```
DELETE /admin/api/unstable/customer_saved_searches/789629109.json
```
Response:
```
HTTP/1.1 200 OK
{}
```
## Retrieves all customers returned by a customer saved search
Retrieves all customers returned by a customer saved search.
### Endpoint
/admin/api/#{api_version}/customer_saved_searches/{customer_saved_search_id}/customers.json (GET)
### Parameters
* api_version (required):
* customer_saved_search_id (required):
* fields: Show only certain fields, specified by a comma-separated list of field names.
* limit: The maximum number of results to show.
* order: Set the field and direction by which to order results.
### Responses
#### 200
Retrieves all customers returned by a customer saved search
Examples:
##### Retrieve customers who match the query for the specified customer saved search
Request:
```
GET /admin/api/unstable/customer_saved_searches/789629109/customers.json
```
Response:
```
HTTP/1.1 200 OK
{"customers":[{"id":207119551,"email":"bob.norman@mail.example.com","accepts_marketing":true,"created_at":"2023-06-14T14:27:29-04:00","updated_at":"2023-06-14T14:30:45-04: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,"tags":"Léon, Noël","last_order_name":"#1001","currency":"USD","phone":"+16136120707","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":"2023-06-14T14:30:45-04:00","marketing_opt_in_level":"single_opt_in","tax_exemptions":[],"sms_marketing_consent":{"state":"not_subscribed","opt_in_level":"single_opt_in","consent_updated_at":"2023-06-14T14:27:29-04:00","consent_collected_from":"OTHER"},"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}}]}
```