CustomerSavedSearch

Version 2019-04

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

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

Customer saved search queries

Use the following table to construct customer search queries:

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

What you can do with CustomerSavedSearch

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

GET /admin/api/2019-04/customer_saved_searches.json?since_id=20610973 Retrieves a list of customer saved searches
GET /admin/api/2019-04/customer_saved_searches/count.json Retrieves a count of all customer saved searches
GET /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
GET /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
POST /admin/api/2019-04/customer_saved_searches.json Creates a customer saved search
PUT /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
DELETE /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search

CustomerSavedSearch properties

created_at read-only	`"created_at": "2012-08-17T10:01:46-04:00"` The date and time (ISO 8601 format) when the customer saved search was created.
id read-only	`"id": 789629109` A unique identifier for the customer saved search.
name	`"name": "Accepts Marketing"` The name given by the shop owner to the customer saved search.
query	`"query": "accepts_marketing:1"` The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at read-only	`"updated_at": "2012-08-17T10:01:46-04:00"` The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2019-04/customer_saved_searches.json?since_id=20610973

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

limit	The maximum number of results to show. (default: `50`, maximum: `250`)
page deprecated	The page of results to show. Removed in version 2019-07. Use [cursor-based pagination](/tutorials/make-paginated-requests-to-rest-admin-api) instead. Sending this parameter will return an error. (default: `1`)
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 after a specified ID

GET /admin/api/2019-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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    }
  ]
}

Retrieve all customer saved searches for a shop

GET /admin/api/2019-04/customer_saved_searches.json

View Response

HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

GET /admin/api/2019-04/customer_saved_searches/count.json

Retrieves a count of all customer saved searches.

since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-04/customer_saved_searches/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 3
}

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

GET /admin/api/2020-04/customer_saved_searches/count.json?since_id=20610973

View Response

HTTP/1.1 200 OK
{
  "count": 2
}

GET /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}.json

Retrieves a single customer saved search.

fields

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

Get one customer saved search by ID

GET /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-22T12:18:22-04:00",
    "query": "accepts_marketing:1"
  }
}

GET /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}/customers.json

Retrieves all customers returned by a customer saved search.

order	Set the field and direction by which to order results. (default: `last_order_date DESC`)
limit	The maximum number of results to show. (default: `50`, maximum: `250`)
fields	Show only certain fields, specified by a comma-separated list of field names.

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

GET /admin/api/2020-04/customer_saved_searches/789629109/customers.json

View Response

HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2020-06-29T12:18:22-04:00",
      "updated_at": "2020-06-29T12:20:53-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,
      "phone": null,
      "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": "2020-06-29T12:20:53-04:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}

POST /admin/api/2019-04/customer_saved_searches.json

Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136104,
    "name": "Spent more than $50",
    "created_at": "2020-06-29T12:20:56-04:00",
    "updated_at": "2020-06-29T12:20:56-04: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": 1068136105,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2020-06-29T12:20:57-04:00",
    "updated_at": "2020-06-29T12:20:57-04:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

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

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "body": "foobar"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}.json

Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-04/customer_saved_searches/789629109.json

{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-29T12:20:59-04:00",
    "query": "accepts_marketing:1"
  }
}

DELETE /admin/api/2019-04/customer_saved_searches/{customer_saved_search_id}.json

Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
}

Version 2019-07

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

Customer saved search queries

Use the following table to construct customer search queries:

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

What you can do with CustomerSavedSearch

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

GET /admin/api/2019-07/customer_saved_searches.json Retrieves a list of customer saved searches
GET /admin/api/2019-07/customer_saved_searches/count.json Retrieves a count of all customer saved searches
GET /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}.json Retrieves a single customer saved search
GET /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}/customers.json Retrieves all customers returned by a customer saved search
POST /admin/api/2019-07/customer_saved_searches.json Creates a customer saved search
PUT /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}.json Updates a customer saved search
DELETE /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}.json Deletes a customer saved search

CustomerSavedSearch properties

created_at read-only	`"created_at": "2012-08-17T10:01:46-04:00"` The date and time (ISO 8601 format) when the customer saved search was created.
id read-only	`"id": 789629109` A unique identifier for the customer saved search.
name	`"name": "Accepts Marketing"` The name given by the shop owner to the customer saved search.
query	`"query": "accepts_marketing:1"` The set of conditions that determines which customers are returned by the saved search. For more information, see Customer saved search queries.
updated_at read-only	`"updated_at": "2012-08-17T10:01:46-04:00"` The date and time (ISO 8601 format) when the customer saved search was last modified.

Endpoints

GET /admin/api/2019-07/customer_saved_searches.json

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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04: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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    }
  ]
}

GET /admin/api/2019-07/customer_saved_searches/count.json

Retrieves a count of all customer saved searches.

since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-04/customer_saved_searches/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 3
}

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

GET /admin/api/2020-04/customer_saved_searches/count.json?since_id=20610973

View Response

HTTP/1.1 200 OK
{
  "count": 2
}

GET /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}.json

Retrieves a single customer saved search.

fields

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

Get one customer saved search by ID

GET /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-22T12:18:22-04:00",
    "query": "accepts_marketing:1"
  }
}

GET /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}/customers.json

Retrieves all customers returned by a customer saved search.

order	Set the field and direction by which to order results. (default: `last_order_date DESC`)
limit	The maximum number of results to show. (default: `50`, maximum: `250`)
fields	Show only certain fields, specified by a comma-separated list of field names.

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

GET /admin/api/2020-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": "2020-06-29T12:18:22-04:00",
      "updated_at": "2020-06-29T12:20:53-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,
      "phone": null,
      "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": "2020-06-29T12:20:53-04:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}

POST /admin/api/2019-07/customer_saved_searches.json

Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136104,
    "name": "Spent more than $50",
    "created_at": "2020-06-29T12:20:56-04:00",
    "updated_at": "2020-06-29T12:20:56-04: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": 1068136105,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2020-06-29T12:20:57-04:00",
    "updated_at": "2020-06-29T12:20:57-04:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

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

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "body": "foobar"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}.json

Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-04/customer_saved_searches/789629109.json

{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-29T12:20:59-04:00",
    "query": "accepts_marketing:1"
  }
}

DELETE /admin/api/2019-07/customer_saved_searches/{customer_saved_search_id}.json

Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
}

Version 2019-10

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

Customer saved search queries

Use the following table to construct customer search queries:

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

What you can do with CustomerSavedSearch

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

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

Endpoints

GET /admin/api/2019-10/customer_saved_searches.json

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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04: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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    }
  ]
}

GET /admin/api/2019-10/customer_saved_searches/count.json

Retrieves a count of all customer saved searches.

since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-04/customer_saved_searches/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 3
}

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

GET /admin/api/2020-04/customer_saved_searches/count.json?since_id=20610973

View Response

HTTP/1.1 200 OK
{
  "count": 2
}

GET /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json

Retrieves a single customer saved search.

fields

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

Get one customer saved search by ID

GET /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-22T12:18:22-04:00",
    "query": "accepts_marketing:1"
  }
}

GET /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}/customers.json

Retrieves all customers returned by a customer saved search.

order	Set the field and direction by which to order results. (default: `last_order_date DESC`)
limit	The maximum number of results to show. (default: `50`, maximum: `250`)
fields	Show only certain fields, specified by a comma-separated list of field names.

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

GET /admin/api/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": "2020-06-29T12:18:22-04:00",
      "updated_at": "2020-06-29T12:20:53-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,
      "phone": null,
      "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": "2020-06-29T12:20:53-04:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}

POST /admin/api/2019-10/customer_saved_searches.json

Creates a customer saved search.

Create a customer saved search

POST /admin/api/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": 1068136104,
    "name": "Spent more than $50",
    "created_at": "2020-06-29T12:20:56-04:00",
    "updated_at": "2020-06-29T12:20:56-04: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": 1068136105,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2020-06-29T12:20:57-04:00",
    "updated_at": "2020-06-29T12:20:57-04:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

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

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "body": "foobar"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json

Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-04/customer_saved_searches/789629109.json

{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-29T12:20:59-04:00",
    "query": "accepts_marketing:1"
  }
}

DELETE /admin/api/2019-10/customer_saved_searches/{customer_saved_search_id}.json

Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-01

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

Customer saved search queries

Use the following table to construct customer search queries:

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

What you can do with CustomerSavedSearch

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

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

Endpoints

GET /admin/api/2020-01/customer_saved_searches.json

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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04: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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    }
  ]
}

GET /admin/api/2020-01/customer_saved_searches/count.json

Retrieves a count of all customer saved searches.

since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-04/customer_saved_searches/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 3
}

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

GET /admin/api/2020-04/customer_saved_searches/count.json?since_id=20610973

View Response

HTTP/1.1 200 OK
{
  "count": 2
}

GET /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json

Retrieves a single customer saved search.

fields

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

Get one customer saved search by ID

GET /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-22T12:18:22-04:00",
    "query": "accepts_marketing:1"
  }
}

GET /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}/customers.json

Retrieves all customers returned by a customer saved search.

order	Set the field and direction by which to order results. (default: `last_order_date DESC`)
limit	The maximum number of results to show. (default: `50`, maximum: `250`)
fields	Show only certain fields, specified by a comma-separated list of field names.

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

GET /admin/api/2020-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": "2020-06-29T12:18:22-04:00",
      "updated_at": "2020-06-29T12:20:53-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,
      "phone": null,
      "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": "2020-06-29T12:20:53-04:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}

POST /admin/api/2020-01/customer_saved_searches.json

Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-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": 1068136104,
    "name": "Spent more than $50",
    "created_at": "2020-06-29T12:20:56-04:00",
    "updated_at": "2020-06-29T12:20:56-04: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": 1068136105,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2020-06-29T12:20:57-04:00",
    "updated_at": "2020-06-29T12:20:57-04:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

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

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "body": "foobar"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json

Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-04/customer_saved_searches/789629109.json

{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-29T12:20:59-04:00",
    "query": "accepts_marketing:1"
  }
}

DELETE /admin/api/2020-01/customer_saved_searches/{customer_saved_search_id}.json

Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-04 (Latest)

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

Customer saved search queries

Use the following table to construct customer search queries:

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

What you can do with CustomerSavedSearch

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

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

Endpoints

GET /admin/api/2020-04/customer_saved_searches.json

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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04: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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    }
  ]
}

GET /admin/api/2020-04/customer_saved_searches/count.json

Retrieves a count of all customer saved searches.

since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-04/customer_saved_searches/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 3
}

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

GET /admin/api/2020-04/customer_saved_searches/count.json?since_id=20610973

View Response

HTTP/1.1 200 OK
{
  "count": 2
}

GET /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json

Retrieves a single customer saved search.

fields

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

Get one customer saved search by ID

GET /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-22T12:18:22-04:00",
    "query": "accepts_marketing:1"
  }
}

GET /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}/customers.json

Retrieves all customers returned by a customer saved search.

order	Set the field and direction by which to order results. (default: `last_order_date DESC`)
limit	The maximum number of results to show. (default: `50`, maximum: `250`)
fields	Show only certain fields, specified by a comma-separated list of field names.

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

GET /admin/api/2020-04/customer_saved_searches/789629109/customers.json

View Response

HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": true,
      "created_at": "2020-06-29T12:18:22-04:00",
      "updated_at": "2020-06-29T12:20:53-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,
      "phone": null,
      "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": "2020-06-29T12:20:53-04:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}

POST /admin/api/2020-04/customer_saved_searches.json

Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "name": "Spent more than $50",
    "query": "total_spent:>50"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_saved_search": {
    "id": 1068136104,
    "name": "Spent more than $50",
    "created_at": "2020-06-29T12:20:56-04:00",
    "updated_at": "2020-06-29T12:20:56-04: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": 1068136105,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2020-06-29T12:20:57-04:00",
    "updated_at": "2020-06-29T12:20:57-04:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

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

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "body": "foobar"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json

Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-04/customer_saved_searches/789629109.json

{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-29T12:20:59-04:00",
    "query": "accepts_marketing:1"
  }
}

DELETE /admin/api/2020-04/customer_saved_searches/{customer_saved_search_id}.json

Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-07 (Release candidate)

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

Customer saved search queries

Use the following table to construct customer search queries:

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

What you can do with CustomerSavedSearch

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

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

Endpoints

GET /admin/api/2020-07/customer_saved_searches.json

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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04: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": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2020-06-22T12:18:22-04:00",
      "updated_at": "2020-06-22T12:18:22-04:00",
      "query": "accepts_marketing:1"
    }
  ]
}

GET /admin/api/2020-07/customer_saved_searches/count.json

Retrieves a count of all customer saved searches.

since_id

Restrict results to after the specified ID

Retrieve a count all customer saved searches

GET /admin/api/2020-04/customer_saved_searches/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 3
}

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

GET /admin/api/2020-04/customer_saved_searches/count.json?since_id=20610973

View Response

HTTP/1.1 200 OK
{
  "count": 2
}

GET /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json

Retrieves a single customer saved search.

fields

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

Get one customer saved search by ID

GET /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-22T12:18:22-04:00",
    "query": "accepts_marketing:1"
  }
}

GET /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}/customers.json

Retrieves all customers returned by a customer saved search.

order	Set the field and direction by which to order results. (default: `last_order_date DESC`)
limit	The maximum number of results to show. (default: `50`, maximum: `250`)
fields	Show only certain fields, specified by a comma-separated list of field names.

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

GET /admin/api/2020-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": "2020-06-29T12:18:22-04:00",
      "updated_at": "2020-06-29T12:20:53-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,
      "phone": null,
      "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": "2020-06-29T12:20:53-04:00",
      "marketing_opt_in_level": "single_opt_in",
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  ]
}

POST /admin/api/2020-07/customer_saved_searches.json

Creates a customer saved search.

Create a customer saved search

POST /admin/api/2020-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": 1068136104,
    "name": "Spent more than $50",
    "created_at": "2020-06-29T12:20:56-04:00",
    "updated_at": "2020-06-29T12:20:56-04: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": 1068136105,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2020-06-29T12:20:57-04:00",
    "updated_at": "2020-06-29T12:20:57-04:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

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

POST /admin/api/2020-04/customer_saved_searches.json

{
  "customer_saved_search": {
    "body": "foobar"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "search_terms": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json

Updates a customer saved search.

Update an existing customer saved search

PUT /admin/api/2020-04/customer_saved_searches/789629109.json

{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed"
  }
}

View Response

HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "This Name Has Been Changed",
    "created_at": "2020-06-22T12:18:22-04:00",
    "updated_at": "2020-06-29T12:20:59-04:00",
    "query": "accepts_marketing:1"
  }
}

DELETE /admin/api/2020-07/customer_saved_searches/{customer_saved_search_id}.json

Deletes a customer saved search.

Delete an existing Customer Saved Search

DELETE /admin/api/2020-04/customer_saved_searches/789629109.json

View Response

HTTP/1.1 200 OK
{
}