CustomerSavedSearch

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

Customer saved search

In the admin, the shop owner searches for customers by applying one or more filters. As soon as the first filter is applied, the shop owner has the option of saving the search as a customer saved search and giving it a name. The customer saved search is created and the shop owner can select the search to see a list of the customers that fit within that query.

CustomerSavedSearch Queries

API value Admin UI value Description
accepts_marketing Accepts marketing Limits the customers returned by the search to those who either accept email marketing or don't.
Valid values are listed below and limit the customers returned by the search who:
  • 0: doesn't accept email marketing.
  • 1: accepts email marketing.
country Located in Limits the customers returned by the search to those based in a specific country.
Valid values are the full name of any country, contained in single quotes.
Examples:
  • 'United States' limits the resulting customers to those from the US.
  • 'Canada' limits the resulting customers to those from Canada.
last_abandoned_order_date Abandoned an order Limits the customers returned by the search to those who abandoned an order within a specific set of dates.
Valid values are listed below and limit the resulting customers to those who abandoned an order...
  • last_week: within the last week.
  • last_month: within the last month.
last_order_date Placed an order Limits the customers returned by the search to those who placed an order within a specific set of dates.
Valid values are listed below and limit the resulting customers to those who placed an order...
  • last_week: within the last week.
  • last_month: within the last month.
  • last_3_months: within the last 3 months.
  • last_year: within the last year.
  • >yyyy-m-d: before the specified date.
  • <yyyy-m-d: after the specified date.
orders_count Orders placed Limits the customers returned by the search to those who placed a certain number of orders.
Valid values are listed below and limit the resulting customers to those who placed...
  • >number_of_orders: fewer than the specified number of orders.
  • <number_of_orders: more than the specified number of orders.
  • number_of_orders: the specified number of orders.
state Account status Limits the customers returned by the search to those whose accounts have a specific status.
Valid values are listed below and limit the resulting customers to those whose status is:
  • declined
  • disabled
  • enabled
  • invited
tag Tagged with Limits the customers returned by the search to those who have a specific tag.
Valid values are any tag that currently applied to any customer, contained in single quotes.
Examples:
  • Big spender limits the resulting customers to those with the tag "Big spender".
  • Favorite limits the resulting customers to those with the tag "Favorite".
total_spent Money spent Limits the customers returned by the search to those who have spent a specific amount of money over their entire history at the shop.
Valid values are listed below and limit the resulting customers to those who spent...
  • >money_amount: less than the specified amount of money.
  • <money_amount: more than the specified amount of money.
  • money_amount: the specified amount of money.

What can you do with CustomerSavedSearch?

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

CustomerSavedSearch Properties

created_at
{ "created_at" : "2012-08-17T10:01:46-04:00" }

The date and time when the customer saved search was created. The API returns this value in ISO 8601 format.

id
{ "id" : 789629109 }

A unique numeric 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 will be returned by the saved search. Queries are covered in more detail in Customer saved search queries.

updated_at
{ "updated_at" : "2012-08-17T10:01:46-04:00" }

The date and time when the customer saved search was last modified. The API returns this value in ISO 8601 format.

Endpoints

GET/admin/customer_saved_searches.json

Get a list of all customer saved searches

page

Page to show

(default: 1)
limit

Amount of results

(default: 50) (maximum: 250)
since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Get all customer saved searches for a shop

GET /admin/customer_saved_searches.json
View Response
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2016-06-13T13:35:06-04:00",
      "updated_at": "2016-06-13T13:35:06-04:00",
      "query": "accepts_marketing:1"
    },
    {
      "id": 20610973,
      "name": "Canadian Snowboarders",
      "created_at": "2016-06-13T13:35:06-04:00",
      "updated_at": "2016-06-13T13:35:06-04:00",
      "query": "country:Canada"
    },
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2016-06-13T13:35:06-04:00",
      "updated_at": "2016-06-13T13:35:06-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    }
  ]
}

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

GET /admin/customer_saved_searches.json?since_id=20610973
View Response
HTTP/1.1 200 OK
{
  "customer_saved_searches": [
    {
      "id": 669439218,
      "name": "Premier Customers",
      "created_at": "2016-06-13T13:35:06-04:00",
      "updated_at": "2016-06-13T13:35:06-04:00",
      "query": "John Smith orders_count:>10 total_spent:>100.00"
    },
    {
      "id": 789629109,
      "name": "Accepts Marketing",
      "created_at": "2016-06-13T13:35:06-04:00",
      "updated_at": "2016-06-13T13:35:06-04:00",
      "query": "accepts_marketing:1"
    }
  ]
}
GET/admin/customer_saved_searches/count.json

Get a count of all customer saved searches

since_id

Restrict results to after the specified ID

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

GET /admin/customer_saved_searches/count.json?since_id=20610973
View Response
HTTP/1.1 200 OK
{
  "count": 2
}

Get a count all customer saved searches

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

Get a single customer saved search

fields

comma-separated list of fields to include in the response

Get one customer saved search by ID

GET /admin/customer_saved_searches/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "customer_saved_search": {
    "id": 789629109,
    "name": "Accepts Marketing",
    "created_at": "2016-06-13T13:35:06-04:00",
    "updated_at": "2016-06-13T13:35:06-04:00",
    "query": "accepts_marketing:1"
  }
}
GET/admin/customer_saved_searches/789629109/customers.json
order

Field and direction to order results by

(default: last_order_date DESC)
page

Page to show

(default: 1)
limit

Amount of results

(default: 50) (maximum: 250)
fields

comma-separated list of fields to include in the response

Get all customers who match the criteria for the specified customer saved search

GET /admin/customer_saved_searches/#{id}/customers.json
View Response
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2016-06-20T13:35:06-04:00",
      "updated_at": "2016-06-20T13:35:06-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "41.94",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "tags": "",
      "last_order_name": "#1001",
      "default_address": {
        "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
      },
      "addresses": [
        {
          "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/customer_saved_searches.json

Create a new Customer Saved Search with multiple terms

POST /admin/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": 1068136104,
    "name": "Spent more than $50 and after 2013",
    "created_at": "2016-06-20T13:40:12-04:00",
    "updated_at": "2016-06-20T13:40:12-04:00",
    "query": "total_spent:>50 order_date:>=2013-01-01"
  }
}

Trying to create a customer saved search without a name will return an error

POST /admin/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"
    ]
  }
}

Create a new Customer Saved Search

POST /admin/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": 1068136105,
    "name": "Spent more than $50",
    "created_at": "2016-06-20T13:40:13-04:00",
    "updated_at": "2016-06-20T13:40:13-04:00",
    "query": "total_spent:>50"
  }
}
PUT/admin/customer_saved_searches/789629109.json

Update an existing Customer Saved Search

PUT /admin/customer_saved_searches/#{id}.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": "2016-06-13T13:35:06-04:00",
    "updated_at": "2016-06-20T13:40:14-04:00",
    "query": "accepts_marketing:1"
  }
}
DELETE/admin/customer_saved_searches/789629109.json

Delete an existing Customer Saved Search

DELETE /admin/customer_saved_searches/#{id}.json
View Response
HTTP/1.1 200 OK
{}