Search Customers

Function

To search customers with specific conditions.
利用特殊條件搜尋顧客列表。

URL

GET <<api_domain>>/v1/customers/search

Request parameters

Parameter	Type	Description	Example
page	`Integer`	Page 頁數 (Default: 1)	`ruby page=1`
per_page	`Integer`	Numbers of Orders per page 每頁顯示 n 筆資料 (Default: 24, Max: `999`)	`ruby per_page=30`
query	`String`	Support searching fields below: 支援搜尋以下欄位: name email phones mobile_phone	`ruby query=shopline`
name	`String`	Customer's Name 顧客姓名 *Support equal or not equal. 支援等於或不等於	`ruby name=Shopline User name=not: Shopline User`
id	`array`	Customer's ID 顧客編號 Multiple Owing to the limit of HTTP GET request, please limit the number of ID in around 200 複數基於HTTP GET query string長度限制，請每次查詢約200個ID內.	`ruby id[]=5ce0d084e388096bdb229a59&id[]=5ce0d084e388096bdb229a78`
email `String`	`String`	Customer's Email 顧客Email *Support equal or not equal. 支援等於或不等於	`ruby [email protected] email=not: [email protected]`
phones	`String`	Customer's Phone 顧客電話 Support equal or not equal. 支援等於或不等於	`ruby phones=0910000123 phones=02-27423586 phones=not: 0910000123`
mobile_phone	`String`	Customer's Mobile Phone 顧客手機 Support equal or not equal. 支援等於或不等於.	`ruby mobile_phone=0910000123 mobile_phone=not: 0910000123`
gender	`String`	Customer's Gender 顧客性別 Gender allows `male` 男性 `female` 女性 `other` 其他Support equal or not equal. 支援等於或不等於.	`ruby gender=male gender=not: male`
membership_tier_id	`String`	Membership Tier 顧客等級 With blank will return customers without membership tier 當帶入空值，將回傳無會員等級之顧客With `not:` will return customers with membership tier 當帶入`not:`，將回傳有會員等級之顧客\ Support equal or not equal. 支援等於或不等於.	`ruby membership_tier_id= membership_tier_id=not: membership_tier_id=5b1e2c48e388094f140000a4`
created_at	`String`	Filter customers by created time 以顧客創造時間作為搜尋依據 Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於Please fill in to the second level. Default value is 00:00:00 if only fill in dates. 請輸入至秒數，若只輸入日期，則會自動帶入當天00:00:00	`ruby created_at=2018-11-11 12:30:30 created_at=not: 2018-11-11 12:30:30 created_at=lt: 2018-11-11 12:30:30 created_at=lte: 2018-11-11 12:30:30 created_at=gt: 2018-11-11 12:30:30 created_at=gte: 2018-11-11 12:30:30`
updated_at	`String`	Filter customers by created time 以顧客更新時間作為搜尋依據 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby updated_at=2018-11-11 12:30:30 updated_at=not: 2018-11-11 12:30:30 updated_at=lt: 2018-11-11 12:30:30 updated_at=lte: 2018-11-11 12:30:30 updated_at=gt: 2018-11-11 12:30:30 updated_at=gte: 2018-11-11 12:30:30`
registered_at	`String`	Filter customers by registered time 以顧客註冊時間作為搜尋依據 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby registered_at=2018-11-11 12:30:30 registered_at=not: 2018-11-11 12:30:30 registered_at=lt: 2018-11-11 12:30:30 registered_at=lte: 2018-11-11 12:30:30 registered_at=gt: 2018-11-11 12:30:30 registered_at=gte: 2018-11-11 12:30:30`
birthday	`String`	Filter customers by birthday 以顧客生日作為搜尋依據 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby birthday=2018-11-11 birthday=not: 2018-11-11 birthday=lt: 2018-11-11 birthday=lte: 2018-11-11 birthday=gt: 2018-11-11 birthday=gte: 2018-11-11`
birth_month	`Integer`	Filter customers by birth month 以顧客生日月份作為搜尋依據 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby birth_month=11 birth_month=not: 11 birth_month=lt: 11 birth_month=lte: 11 birth_month=gt: 11 birth_month=gte: 11`
credit_balance	`String`	Filter customers by credit balance 以購物金作為搜尋依據 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby credit_balance=100 credit_balance=not: 100 credit_balance=lt: 100 credit_balance=lte: 100 credit_balance=gt: 100 credit_balance=gte: 100`
is_member	`String`	Filter member customers. 搜尋是會員的顧客	`ruby is_member=true is_member=false`
is_blacklisted	`String`	Filter Blacklisted Customers. 搜尋是黑名單的顧客	`ruby is_blacklisted=true is_blacklisted=false`
is_subscribed_marketing_email	`String`	Filter Customers by Marketing Acceptance. 搜尋接受優惠宣傳的顧客	`ruby is_subscribed_marketing_email=true is_subscribed_marketing_email=false`
ref_user_id	`String`	Third party custom customer id 第三儲存之顧客ID	`ruby ref_user_id= MEMBR000000000000019034194`

🚧
Note
Please note the following pagination limitations when using this API:

The request will fail if page * per_page exceeds 10,000.

Example: If per_page = 50, the maximum value for page should be 200. Exceeding this value will result in an error.

使用此 API 時，請注意以下分頁限制：

當 page * per_page 大於 10,000 時，請求將會失敗。

範例：如果 per_page = 50，page 最大值應為 200，超過此值請求將會失敗。

Response fields

Field	Type	Description	Example
items	Get Customer	Array of customer	Please check the link on the left
pagination	Pagination	Pagination Data	Please check the link on the left

Request Example ( Normal Case)

curl -X GET \
  '<<api_domain>>/v1/customers/search?page=1&per_page=30&query=shopline&is_member=' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearar {access_token}' \
  -H 'User-Agent: shopline'

Request Example ( Search by specific fields)

You can pass search_fields parameter to specify search fields.

curl --location --request GET '<<api_domain>>/v1/customers/search?query=1232&search_fields[]=phones&search_fields[]=mobile_phone' \
--header 'Authorization: Bearer ${access_token}'

Response Example

JSON sample

{
  "items": [
{
    "id": "5ce0d084e388096bdb229a59",
    "name": "joanne+m12",
    "email": "[email protected]",
    "gender": null,
    "birthday": "1996-03-05",
    "birth_year": 1996,
    "birth_month": 3,
    "birth_day": 5,
    "phones": [],
    "mobile_phone": "0922165898",
    "mobile_phone_verified": true,
    "mobile_phone_country_calling_code": "886",
    "locale_code": "zh-hant",
    "order_count": 0,
    "orders_total_sum": {
        "cents": 0,
        "currency_symbol": "NT$",
        "currency_iso": "TWD",
        "label": "",
        "dollars": 0.0
    },
    "is_member": true,
    "is_blacklisted": false,
    "is_subscribed_marketing_email": true,
    "credit_balance": 150,
    "custom_data": [],
    "membership_tier": null,
    "delivery_addresses": [],
    "subscribed_email_types": [
        "marketing.news"
    ],
    "ref_user_id": null,
    "line_id": null,
    "updated_at": "2019-06-27T16:04:23.012+00:00",
    "created_at": "2019-05-19T03:41:56.670+00:00",
    "current_sign_in_at": "2019-05-19T03:42:33.096+00:00",
    "last_sign_in_at": "2019-05-19T03:42:33.096+00:00",
    "registered_at": "2019-05-19T03:41:56.403+00:00",
    "registered_from_channel": {
        "id": "5c135ad0e388097eb33d8ae4",
        "name": {
            "zh-hant": "高雄店"
        },
        "platform": "shop_crm",
        "merchant_id": "5b457ad9e388095dcb000006",
        "updated_at": "2019-01-21T04:14:12.459+00:00",
        "created_at": "2018-12-14T07:25:04.458+00:00",
        "currency_code": "TWD"
    },
    "created_by": "shop_crm"
}],
  "pagination": {
    "current_page": 1,
    "per_page": 24,
    "total_pages": 1,
    "total_count": 1
  }
}