HomeGuidesAPI ReferenceChangelogDiscussions
HomeLog In
Guides

Search Customers

Function

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

URL

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

Request parameters

ParameterTypeDescriptionExample
pageIntegerPage
頁數
(Default: 1)
ruby page=1
per_pageIntegerNumbers of Orders per page
每頁顯示 n 筆資料
(Default: 24, Max: 999)
ruby per_page=30
queryStringSupport searching fields below:
支援搜尋以下欄位:
name
email
phones
mobile_phone
ruby query=shopline
nameStringCustomer's Name
顧客姓名

- *Support equal or not equal.
支援 等於 或 不等於
ruby name=Shopline User name=not: Shopline User
idarrayCustomer'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
StringCustomer's Email
顧客Email

- *Support equal or not equal.
支援 等於 或 不等於
ruby [email protected] email=not: [email protected]
phonesStringCustomer's Phone
顧客電話

- Support equal or not equal.
支援 等於 或 不等於
ruby phones=0910000123 phones=02-27423586 phones=not: 0910000123
mobile_phoneStringCustomer's Mobile Phone
顧客手機

- Support equal or not equal.
支援 等於 或 不等於.
ruby mobile_phone=0910000123 mobile_phone=not: 0910000123
genderStringCustomer's Gender
顧客性別

- Gender allows
male 男性
female 女性
other 其他Support equal or not equal.
支援 等於 或 不等於.
ruby gender=male gender=not: male
membership_tier_idStringMembership 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_atStringFilter 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_atStringFilter 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_atStringFilter 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
birthdayStringFilter 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_monthIntegerFilter 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_balanceStringFilter 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_memberStringFilter member customers.
搜尋是會員的顧客
ruby is_member=true is_member=false
is_blacklistedStringFilter Blacklisted Customers.
搜尋是黑名單的顧客
ruby is_blacklisted=true is_blacklisted=false
is_subscribed_marketing_emailStringFilter Customers by Marketing Acceptance.
搜尋接受優惠宣傳的顧客
ruby is_subscribed_marketing_email=true is_subscribed_marketing_email=false
ref_user_idStringThird 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

FieldTypeDescriptionExample
itemsGet CustomerArray of customerPlease check the link on the left
paginationPaginationPagination DataPlease 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
  }
}