# 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.

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.
## Resource Properties ### CustomerSavedSearch * created_at: The date and time (ISO 8601 format) when the customer saved search was created. * Type: x-string * Example: "2012-08-17T10:01:46-04:00" * id: A unique identifier for the customer saved search. * Type: x-string * Example: 789629109 * name: The name given by the shop owner to the customer saved search. * Type: x-string * Example: "Accepts Marketing" * query: The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries. * Type: x-string * Example: "accepts_marketing:1" * updated_at: The date and time (ISO 8601 format) when the customer saved search was last modified. * Type: x-string * Example: "2012-08-17T10:01:46-04:00" ## Retrieves a list of customer saved searches Retrieves a list of customer saved searches. 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 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}}]} ```