Get Customer

Function

To get detailed information for a specific customer with its ID
使用顧客ID獲取特定一個顧客的詳細資料

URL

GET <<api_domain>>/v1/customers/:id

Request parameters

Parameter	Type	Description	Example
id *Required	`String`	Customer unique ID 顧客ID	`ruby 5a55b3c973746f507e120000`
excludes[]	`String`	Could exclude certain parameters in the response 結果要排除哪些參數	`ruby excludes[]=status`
fields[]	`String`	Could only show certain parameters in the response 結果只顯示哪些參數 [Parameters] `membership_tier_gap` Show the total purchase amount needed for upgrading to next membership tier or extending current membership tier. 若要升等或續會，需要再累積多少消費金額	`ruby fields[]=status` `ruby fields[]= membership_tier_gap`
include_fields[]	`String`	Provide additional attributes in the response 在回應中添加哪些參數 [Parameters] `referrer_data` Customer's member referral data 此顧客註冊時的推薦人 SHOPLINE ID 以及名字 `subscription` Customer's subscription 此顧客的 SMS 以及 email 訂閱狀態	`include_fields[]=referrer_data`

Response fields

Field	Type	Description	Example
id	`String`	Customer Unique ID 顧客ID	5ce0d084e388096bdb229a59
name	`String`	Customer Name 顧客姓名	Shopline User
email	`String`	Customer Email 顧客電子郵件	[email protected]
gender	`String`	Customer Gender 顧客性別	male
birthday	`String`	Customer Birthday 顧客生日 ***Please use birth_year, birth_month, birth_day instead. The field is compatible with the old version. 此欄位為舊版相容用，請使用 birth_year, birth_month, birth_day 代替。 If birth_year is null, then the default year is 1904. 如果 birth_year 為 null, 則預設為 1904 年 If birth_month is null, then the default month is 1. 如果 birth_month 為 null, 則預設為 1 月。 If birth_day is null, then the default day is 1. 如果 birth_day 為 null, 則預設為 1 日。 If birth_year, birth_month, birth_day are all null, then fallback to original birthday. 如果 birth_year, birth_month, birth_day 都為 null, 則回傳原本的 birthday。	2013-06-01
birth_year	`Integer`	Customer Birth Year 顧客生日(年)	2000
birth_month	`Integer`	Customer Birth Month 顧客生日(月)	6
birth_day	`Integer`	Customer Birth Day 顧客生日(日)	1
memo	`String`	Customer memo 顧客備註	高級客戶
phones	`Array`	Customer Phones 顧客電話
mobile_phone	`String`	Customer Mobile Phone 顧客手機	0910000123
mobile_phone_verified	`Boolean`	Mobile Phone is Verified or not 是否手機驗證	true
mobile_phone_country_calling_code	`String`	Country Code of Mobile Phone 手機號碼國碼	886
locale_code	`String`	Customer Locale Code 顧客使用前台之語言	zh-hant
order_count	`Integer`	Customer Order Number 顧客累積訂單數	1
orders_total_sum	Money	Customer Orders Total Sum 顧客累積訂單資訊	Please check the link on the left
is_member	`Boolean`	Is the customer a member? 顧客是否為會員？	true
is_blacklisted	`Boolean`	Is the customer in black-list? 顧客是否在黑名單？	false
is_subscribed_marketing_email	`Boolean`	Does the customer subscribe marketing email? 顧客是否接受優惠宣傳？	true
credit_balance	`Integer`	Current Customer Credits 顧客購物金餘額	500
member_point_balance	`Integer`	Current Member Points 顧客會員點數餘額	30
custom_data	Custom Fields	Custom Field Data 顧客設定客製化欄位資訊	Please check the link on the left
membership_tier	Membership Tiers	Membership Tier Data 顧客會員等級 - null :一般會員	Please check the link on the left
delivery_addresses	DeliveryAddress (接受陣列)	Customer's Delivery Addresses 顧客送貨地址	Please check the link on the left
subscribed_email_types	`Array`	Subscribed Email Types 訂閱消息類型	marketing news
subscriptions	`Array`	subscriptions 訂閱資訊	subscriptions: [ { "platform": "SMS", "is_active": true } ]
ref_user_id	`String`	For third party to put custom user_id 可供儲存第三方顧客ID	SL001
line_id	`String`	LINE ID 顧客Line ID from line profile api	null
updated_at	`DateTime`	Customer Last Updated Time 顧客最後更新資訊時間 - *UTC Time	2018-07-31T03:57:36.409+00:00
created_at	`DateTime`	Customer Created Time 顧客資料創造時間 - *UTC Time	2018-01-10T06:33:45.231+00:00
current_sign_in_at	`DateTime`	Timestamp updated when customers sign in 顧客最近一次登入時間 - *UTC Time	2018-07-31T03:49:52.725+00:00
last_sign_in_at	`DateTime`	Holds the timestamp of the previous sign in 顧客最近一次登入時間之前的登入時間 (倒數第二次登入的時間) - *UTC Time	2018-04-02T04:02:23.391+00:00
registered_at	`DateTime`	Customer register's Date and time 顧客註冊時間 - *UTC Time	2018-01-10T06:33:45.231+00:00
registered_from_channel (Only applied to O2O plan) (O2O 商家適用)	Channel	Registration Channel 會員實體註冊來源
created_by	`String`	顧客建立來源 “`shop`” 來自前台網站 “`admin`” 來自後台 “`openapi`” 由 open api 創建 “`shop_crm`” 來自 kiosk “`pos`” 來自 POS "`mc`" 來自訊息中心 "`sc_manual_order`"來自社群自建訂單 "`shopper_app`"來自商家 app	shop admin openapi shop_crm pos mc sc_manual_order shopper_app
tags	`Array` or String	自定義標籤	`["Tag A", "Tag B"]`
tier_expires_at	`DateTime`	Membership expiry date 會籍到期日 - *UTC Time	"2021-12-18T15:59:59.999+00:00"
offline_referral_registered_at	`String`	門市綁定日期時間	(只有使用 Smart OMO 服務的店家會有此欄位的值)
offline_referral_channel_id	`String`	門市 ID	(只有使用 Smart OMO 服務的店家會有此欄位的值)
offline_referral_agent_id	`String`	門市推薦人 ID	(只有使用 Smart OMO 服務的店家會有此欄位的值)
confirmed_at	`DateTime`	timestamp of the email verification 顧客確認電郵注册時間 - *UTC Time	`2021-12-06T02:37:06.363+00:00`
membership_tier_gap	membership_tier_gap entity	升到到下一會員等級所需的相關資訊
mobile_phone_verified	`Boolean`	Mobile Phone Verification Status
email_verified	`Boolean`	Email Verification Status
unconfirmed_email	`String`	Pending to verify Email	nil

membership_tier_gap entity

Field	Type	Description	Example
next_tier	MembershipTier	下一個會員等級的資訊
next_discount	`Float`	下一個會員等級的折扣 *若沒有優惠則回傳 `null`	20
user_spending	`Number`	會員在指定期限內累積的消費金額 (在 Admin 會員分級“會員升級條件”可以設定指定期限) *若沒有下一級則回傳 `null`	2000 The number is same as cents in the currency
next_total_spending	`Number`	The amount of upgrading to next membership tier 升等到下一會員等級所需之消費金額(Admin 設定的升級金額條件) *若沒有下一級則回傳 `null`	5000 The number is same as cents in the currency
extend_total_spending	`Number`	The amount of extending in current membership tier 續會目前會員等級所需之消費金額(Admin 設定的續會金額條件) *若沒有設定則回傳 `null`	3000 The number is same as cents in the currency

Response Example

JSON sample

{
    "id": "5ce0d084e388096bdb229a59",
    "name": "joanne+m12",
    "email": "[email protected]",
    "gender": null,
    "birthday": "1996-03-05",
    "birth_year": 1996,
    "birth_month": 3,
    "birth_day": 5,
    "memo": "Hi I am customer",
    "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",
    "offline_referral_registered_at": null,
    "offline_referral_channel_id": null,
    "offline_referral_agent_id": null,
    "mobile_phone_verified": true,
    "email_verified": true,
    "unconfirmed_email": nil,
    "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"
  	"tier_expires_at": "2021-12-18T15:59:59.999+00:00"
}

JSON example with mobile_phone without phones

{
    "id": "606d4051c6febd0022d13447",
    "name": "philip+blackhole1617772625",
    "email": "[email protected]",
    "gender": "male",
    "birthday": "2000-11-11",
    "memo": "Hi I am customer",
    "phones": [
        "0910123456",
        "02-27423586",
        "+886912345678"
    ],
    "mobile_phone": null,
    "mobile_phone_verified": false,
    "mobile_phone_country_calling_code": null,
    "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": 0,
    "member_point_balance": 0,
    "custom_data": [],
    "membership_tier": null,
    "delivery_addresses": [
        {
            "city": "Taipei",
            "postcode": "10560",
            "address_1": "光復北路11巷44號14樓",
            "address_2": "松山區",
            "recipient_name": "marry",
            "recipient_phone": "0227423966",
            "country": "TW",
            "state": null,
            "key": null,
            "layer1": null,
            "layer2": null,
            "layer3": null,
            "district": null,
            "logistic_codes": null
        },
        {
            "city": "Taipei",
            "postcode": "10560",
            "address_1": "光復北路11巷44號14樓",
            "address_2": "松山區",
            "recipient_name": "marry",
            "recipient_phone": "0227423966",
            "country": "TW",
            "state": null,
            "key": null,
            "layer1": null,
            "layer2": null,
            "layer3": null,
            "district": null,
            "logistic_codes": null
        }
    ],
    "subscribed_email_types": [
        "marketing.news"
    ],
    "ref_user_id": null,
    "line_id": null,
    "facebook_id": null,
    "updated_at": "2021-04-07T05:17:05.544+00:00",
    "created_at": "2021-04-07T05:17:05.406+00:00",
    "current_sign_in_at": null,
    "last_sign_in_at": null,
    "registered_at": "2021-04-07T05:17:05.368+00:00",
    "created_by": "mc",
    "tags": [],
    "offline_referral_registered_at": null,
    "offline_referral_channel_id": null,
    "offline_referral_agent_id": null,
    "customer_authentication_linkings": [],
    "tier_expires_at": null
}