Search customers

/customers/search

Search for customers by specified parameters.

Request body parameters

Parameters that you can send in the request body in JSON format, for example:
{"email": "[email protected]","first_name": "James"}

Title	Type	Description	Required?
email	string	Email of the customer	No
first_name	string	First name of the customer	No
last_name	string	Last name of the customer	No
address	object containing arrays	One or multiple addresses assigned to the customer	No
address.shipping.first_name	string	First name for shipping	No
address.shipping.last_name	string	Last name for shipping	No
address.shipping.company	string	Company for shipping	No
address.shipping.street	string	Street name for shipping	No
address.shipping.suite	string	Suite for shipping	No
address.shipping.city	string	City for shipping	No
address.shipping.country	string	Country for shipping, 2-letter code as per ISO 3166-1	No
address.shipping.state	string	State/province/region for shipping, 2-letter code as per ISO 3166-2	No
address.shipping.zip	string	Zip/postal code for shipping	No
address.billing.first_name	string	First name for billing	No
address.billing.last_name	string	Last name for billing	No
address.billing.street	string	Street name for billing	No
address.billing.suite	string	Suite for billing	No
address.billing.city	string	City for billing	No
address.billing.country	string	Country for billing, 2-letter code as per ISO 3166-1	No
address.billing.state	string	State/province/region for billing, 2-letter code as per ISO 3166-2	No
address.billing.zip	string	Zip/postal code for billing	No
address.phone	string	Phone for the address	No
notes	string	Notes about the customer, optionally set by the store owner	No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"email": "[email protected]","first_name": "James"}

Title	Type	Description
id	int	ID of the customer
email	string	Email of the customer
first_name	string	First name of the customer
last_name	string	Last name of the customer
address	object containing arrays	One or multiple addresses assigned to the customer
address.id	id	ID of the address
address.shipping.first_name	string	First name for shipping
address.shipping.last_name	string	Last name for shipping
address.shipping.company	string	Company for shipping
address.shipping.street	string	Street name for shipping
address.shipping.suite	string	Suite for shipping
address.shipping.city	string	City for shipping
address.shipping.country	string	Country for shipping, 2-letter code as per ISO 3166-1
address.shipping.state	string	State/province/region for shipping, 2-letter code as per ISO 3166-2
address.shipping.zip	string	Zip/postal code for shipping
address.billing.first_name	string	First name for billing
address.billing.last_name	string	Last name for billing
address.billing.street	string	Street name for billing
address.billing.suite	string	Suite for billing
address.billing.city	string	City for billing
address.billing.country	string	Country for billing, 2-letter code as per ISO 3166-1
address.billing.state	string	State/province/region for billing, 2-letter code as per ISO 3166-2
address.billing.zip	string	Zip/postal code for billing
address.phone	string	Phone for the address
payment.type	string	Type of payment method. Can be: Visa, American Express, MasterCard, Discover, JCB, Diners Club, PayPal
payment.last4	string	Last 4 digits of the card number, if paid by card
notes	string	Notes about the customer, optionally set by the store owner
statistics.last_purchase	int	Timestamp of last purchase by the customer
statistics.order_count	int	Number of orders the customer has placed
statistics.lifetime_spent	int	Amount of money spent by customer on this store
orders	array of ints	Array of the customer's order IDs
tags	array of strings	Array containing the tags of all the products that the customer bought
created_at	int	Timestamp of the customer creation time
updated_at	int	Timestamp of the customer last update time

Notes

• Addresses can be managed manually from the customer profile or flow from orders. Changing an address in a customer profile does not affect orders, but changing the address in an order may affect it in the customer profile.

Sample request

Find the customer with shipping country United States who placed order ID 339 and has 7 orders in total.

POST https://mystore.commercehq.com/api/v1/customers/search
{
    "address": {
        "shipping_country": "US"
    },
    "orders": [339],
    "order_count": 7
}

Sample response

{
  "items": [
    {
      "id": 6,
      "email": "[email protected]",
      "first_name": "James",
      "last_name": "C Smith",
      "address": [
        {
          "id": 7,
          "shipping": {
            "first_name": "James",
            "last_name": "C Smith",
            "company": null,
            "street": "46 Leatherwood St.",
            "suite": "1432",
            "city": "North Hollywood",
            "country": "US",
            "state": "CA",
            "zip": "91605"
          },
          "billing": {
            "first_name": "James",
            "last_name": "C Smith",
            "street": "46 Leatherwood St.",
            "suite": "1432",
            "city": "North Hollywood",
            "country": "US",
            "state": "CA",
            "zip": "91605"
          },
          "phone": "any string here"
        }
      ],
      "payment": [],
      "notes": "Some Notes about customer",
      "statistics": {
        "last_purchase": null,
        "order_count": 0,
        "lifetime_spent": 0
      },
      "orders": [],
      "tags": [],
      "created_at": 1485004452,
      "updated_at": 0
    },
    {
      "id": 3,
      "email": "[email protected]",
      "first_name": "Ahmet",
      "last_name": "Zahmut",
      "address": [
        {
          "id": 3,
          "shipping": {
            "first_name": "Ahmet",
            "last_name": "Zahmut",
            "company": null,
            "street": "12 Bomber av.",
            "suite": "suite 1322",
            "city": "New York",
            "country": "US",
            "state": "NY",
            "zip": "M4G 2K6"
          },
          "billing": {
            "first_name": "Ahmet",
            "last_name": "Zahmut",
            "street": "12 Bomber av.",
            "suite": "suite 1322",
            "city": "New York",
            "country": "US",
            "state": null,
            "zip": "M4G 2K6"
          },
          "phone": ""
        }
      ],
      "payment": [
        {
          "type": "Visa",
          "last4": "1111"
        }
      ],
      "notes": null,
      "statistics": {
        "last_purchase": 1484826373,
        "order_count": 1,
        "lifetime_spent": 52
      },
      "orders": [
        4
      ],
      "tags": [],
      "created_at": 1484826370,
      "updated_at": 0
    }
  ],
  "_links": {
    "self": {
      "href": "http://dummy-api.com/api/v1/customers/search?page=1"
    }
  },
  "_meta": {
    "totalCount": 2,
    "pageCount": 1,
    "currentPage": 1,
    "perPage": 20
  }
}