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_gapShow the total purchase amount needed for upgrading to next membership tier or extending current membership tier. 若要升等或續會，需要再累積多少消費金額 | ruby fields[]=statusruby fields[]= membership_tier_gap |
| include_fields[] | String | Provide additional attributes in the response 在回應中添加哪些參數 [Parameters] referrer_dataCustomer's member referral data 此顧客註冊時的推薦人 SHOPLINE ID 以及名字 subscriptionCustomer'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 |
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 |
| 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 | 升到到下一會員等級所需的相關資訊 | |
| 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 | Information on the next membership tier. 下一個會員等級的資訊 | |
| next_discount | Float | Discount for the next membership tier. 下一個會員等級的折扣 *若沒有優惠則回傳 null | 20 |
| user_spending | Number | The upgrade spending amount accumulated by a member within a specified period. 會員在指定期限內累積的升級消費金額 （在 Admin 會員分級“會員升級條件”可以設定指定期限） *若沒有下一級則回傳 null | 2000 The number is same as cents in the currency |
| user_spendings_for_extend | Number | The renewal spending amount accumulated by a member within a specified period. 會員在指定期限內累積的續會消費金額 （在 Admin 會員分級“會員續會條件”可以設定指定期限） *若當前會籍為永久期限則回傳 nil | 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
- 升到下個等級的差額 Balance to upgrade to the next level =
next_total_spending-user_spending- 續會原等級的差額 Balance to renew the current level =
extend_total_spending-user_spendings_for_extend
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,
"google_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,
"google_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
}
Updated 2 days ago