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? 顧客是否接受 Email 優惠宣傳？ Note: 訂閱資訊請參考 `subscriptions` 欄位	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": false }, { "platform": "email", "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
facebook_id	`String`	FACEBOOK ID 顧客Facebook ID
google_id	String	GOOGLE ID 顧客Google ID	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	Next membership tier's info 升到到下一會員等級所需的相關資訊
current_membership_tier_info	current_membership_tier_info	Current membership tier's info 現時的會員等級的資料 Note：Members without a membership level (i.e., regular members) will not receive this field in the response. 沒有會員等級的一般會員不會回傳此欄位
mobile_phone_verified	`Boolean`	Mobile Phone Verification Status
email_verified	`Boolean`	Email Verification Status
unconfirmed_email	`String`	Pending to verify Email	nil
customer_authentication_linkings	`Array`	3rd Party Customer Authentication （SSO） SSO 第三方串接相關資訊備註：串接 SSO 的會員 ID 不會存在 `ref_user_id`，會存在`customer_authentication_linkings` 中的 `ref_id`	"customer_authentication_linkings": [ { "_id": "6360c5e74835a50010314af9", "created_at": "2022-11-01T07:08:23.185Z", "customer_authentication_id": "6050398ea3546c0032a7ed32", "merchant_id": "6037452b4bf8b200305d7ed6", "platform": null, "ref_id": "739790", "ref_info": { "wmid": "739790", "email": "[email protected] ", "name": "lowdown0619", "profile": "womany member" }, "status": "active", "updated_at": "2022-11-01T07:08:23.185Z", "user_id": "6360c5e6b2c2bb0012d3e2a5" } ]

membership_tier_gap entity

Field	Type	Description	Example
next_tier	MembershipTier	Information on the next membership tier. 下一個會員等級的資訊 Note最高階會員沒有 next tier（"next_tier": null）
next_discount	`Float`	Discount for the next membership tier. 下一個會員等級的折扣若沒有優惠則回傳 `null`	20
user_spending	`Number`	The amount used to determine if a member meets the upgrade criteria, based on the "Membership Upgrade Condition" in the SHOPLINE Admin: For "Single Purchase," returns the highest order amount that meets the threshold during the membership period, or 0 if none meet the threshold. For "Purchase within specified period," returns the total spending within that period. Returns `null` if the member is already at the highest tier.用於判斷會員是否符合升級條件的消費金額，依據 Admin 中的「會員升級條件」設定決定回傳值：若條件為「單次購物」，檢查目前會籍期間內是否有任一筆訂單達到門檻。若有訂單達門檻，則回傳金額最高者；若皆未達門檻，回傳 0。若條件為「指定期限內購物」，回傳在指定期限內的累積消費金額。若會員已達最高等級，則回傳 `null`。	2000 The number is same as cents in the currency
user_spendings_for_extend	`Number`	The amount used to determine if a member meets the extend criteria, based on the "Membership extension condition" in the SHOPLINE Admin: For "Single Purchase," returns the highest order amount that meets the threshold during the membership period, or 0 if none meet the threshold. For "Purchase within specified period," returns the total spending within that period. Returns `null` if the current membership has a permanent duration.用於判斷會員是否符合續會條件的消費金額，依據 Admin 中的「會員續會條件」設定決定回傳值：若條件為「單次購物」，檢查目前會籍期間內是否有任一筆訂單達到門檻。若有訂單達門檻，則回傳金額最高者；若皆未達門檻，回傳 0。若條件為「指定期限內購物」，回傳在指定期限內的累積消費金額。若當前會籍為永久期限，則回傳 `null`。	0 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

會員升級/續會差額計算方式 Calculating membership upgrade/renewal balance

If the condition is "Single Purchase":

Upgrade Difference:
- If user_spending > 0, it means the upgrade threshold has been met. The system will return the order with the highest amount among the qualifying orders.
- If user_spending = 0, then the difference = next_total_spending - user_spending — which is essentially equal to next_total_spending, since the latter is 0.
Extension Difference:
- If user_spendings_for_extend > 0, it means the extension threshold has been met. The system will return the order with the highest amount among the qualifying orders.
- If user_spendings_for_extend = 0, then the difference = extend_total_spending - user_spendings_for_extend — which is essentially equal to extend_total_spending, since the latter is 0.
Note: Neither user_spending nor user_spendings_for_extend can be less than 0.

If the condition is "Spending within a specified period":

Upgrade Difference = next_total_spending - user_spending
Extension Difference = extend_total_spending - user_spendings_for_extend

若條件為「單次購物」：

升級差額：
- 若 user_spending > 0，表示已達升級門檻，此時會回傳達門檻訂單中金額最高者；
- 若 user_spending = 0，差額 = next_total_spending - user_spending
  - 其實就等同於 next_total_spending，因為要減去的後者是 0
續會差額：
- 若 user_spendings_for_extend > 0，表示已達續會門檻，此時會回傳達門檻訂單中金額最高者；
- 若 user_spendings_for_extend = 0，差額 = extend_total_spending - user_spendings_for_extend
  - 其實就等同於 extend_total_spending，因為要減去的後者是 0
補充：user_spending 和 user_spendings_for_extend 不會有 <0 的情況

若條件為「指定期限內購物」：

升級差額 = next_total_spending - user_spending
續會差額 = extend_total_spending - user_spendings_for_extend

current_membership_tier_info entity

Field	Type	Description	Example
id	`String`	Membership tier's ID 會員等級ID	"66f27419fe4e57003f7017b6"
level	`Integer`	Level of Current Membership Tier 等級高低	4
name_translations	object	Json Object with key is the language code and value is the translation string JSON 物件，鍵為語言代碼，值為對應的翻譯字串	{ "zh-hant": "最高級別" }*
merchant_id	`String`	Merchant ID	"5e958a8f12743200434653fc"
member_count	`Integer`	Number of members in this membership tier 這個會員級別的會員人數	1
exclusive_product_count	`Integer`	Number of exlcusive products in this membership tier 這個會員級別不能購買的產品數目	0
promotion_count	`Integer`	Number of promotions in this membership tier 這個會員級別的優惠數目	1
member_discount_percentage	`Number`	這個會員等級適用的折扣優惠	40.0
valid_period	object	Valid period of this membership tier 這個會員級別的有效時段	{ "type": "unlimited", "timevalue": "2", "time_unit": "month" }
membership_tier_rules	`Array`	Rules of the member tier Please refer to the membership_tier_rules entity 會員分級的規則詳情可參閱 membership_tier_rules entity	[ { "_id": "67db8ce181414d003c03e9fb", "condition_interval": { "type": "single_purchase", "time_value": "1", "time_unit": "month" }, "created_at": null, "effect_interval": { "type": "within_interval", "time_value": "1", "time_unit": "month" }, "effect_type": "upgrade", "total_spending": { "cents": 1000, "currency_symbol": "NT$", "currency_iso": "TWD", "label": "NT$1,000", "dollars": 1000.0 }, "updated_at": null }, { "_id": "67db8ce181414d003c03e9fc", "condition_interval": { "type": "within_interval", "time_value": "1", "time_unit": "month" }, "created_at": null, "effect_interval": { "type": "within_interval", "time_value": "1", "time_unit": "month" }, "effect_type": "extend", "total_spending": { "cents": 1000, "currency_symbol": "NT$", "currency_iso": "TWD", "label": "NT$1,000", "dollars": 1000.0 }, "updated_at": null } ]*
created_at	`DateTime`		"2024-09-24T08:11:05.029Z"
updated_at	`DateTime`		"2025-03-20T03:35:59.353Z"

Response Example

JSON sample

JSON example with mobile_phone without phones