Home
Guides

Get Customer

Function

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

URL

GET API_DOMAIN/v1/customers/:id

Request parameters

ParameterTypeDescriptionExample
id
*Required		StringCustomer unique ID
顧客ID
ruby
5a55b3c973746f507e120000
excludes[]StringCould 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

FieldTypeDescriptionExample
idStringCustomer Unique ID
顧客ID		5ce0d084e388096bdb229a59
nameStringCustomer Name
顧客姓名		Shopline User
emailStringCustomer Email
顧客電子郵件		[email protected]
genderStringCustomer Gender
顧客性別		male
birthdayStringCustomer 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_yearIntegerCustomer Birth Year
顧客生日(年)		2000
birth_monthIntegerCustomer Birth Month
顧客生日(月)		6
birth_dayIntegerCustomer Birth Day
顧客生日(日)		1
memoStringCustomer memo
顧客備註		高級客戶
phonesArrayCustomer Phones
顧客電話
mobile_phoneStringCustomer Mobile Phone
顧客手機		0910000123
mobile_phone_verifiedBooleanMobile Phone is Verified or not
是否手機驗證		true
mobile_phone_country_calling_codeStringCountry Code of Mobile Phone
手機號碼國碼		886
locale_codeStringCustomer Locale Code
顧客使用前台之語言		zh-hant
order_countIntegerCustomer Order Number
顧客累積訂單數		1
orders_total_sumMoneyCustomer Orders Total Sum
顧客累積訂單金額		Please check the link on the left
is_memberBooleanIs the customer a member?
顧客是否為會員？		true
is_blacklistedBooleanIs the customer in black-list?
顧客是否在黑名單？		false
is_subscribed_marketing_emailBoolean

Does the customer subscribe marketing email?
顧客是否接受 Email 優惠宣傳？

Note: 訂閱資訊請參考 subscriptions 欄位

true
credit_balanceIntegerCurrent Customer Credits
顧客購物金餘額		500
member_point_balanceIntegerCurrent Member Points
顧客會員點數餘額		30
custom_dataCustom FieldsCustom Field Data
顧客設定客製化欄位資訊		Please check the link on the left
membership_tierMembership TiersMembership Tier Data
顧客會員等級
  • null :一般會員
Please check the link on the left
delivery_addressesDeliveryAddress
(接受陣列)		Customer's Delivery Addresses
顧客送貨地址		Please check the link on the left
subscribed_email_typesArraySubscribed Email Types
訂閱消息類型		marketing news
subscriptionsArraysubscriptions 訂閱資訊subscriptions:
[
{
"platform": "sms",
"is_active": false
},
{
"platform": "email",
"is_active": true
}
]
ref_user_idStringFor third party to put custom user_id
可供儲存第三方顧客ID		SL001
line_idStringLINE ID
顧客Line ID
from line profile api		null
facebook_idStringFACEBOOK ID
顧客Facebook ID
google_idStringGOOGLE ID
顧客Google ID		null
updated_atDateTimeCustomer Last Updated Time
顧客最後更新資訊時間
  • *UTC Time
2018-07-31T03:57:36.409+00:00
created_atDateTimeCustomer Created Time
顧客資料創造時間
  • *UTC Time
2018-01-10T06:33:45.231+00:00
current_sign_in_atDateTimeTimestamp updated when customers sign in
顧客最近一次登入時間
  • *UTC Time
2018-07-31T03:49:52.725+00:00
last_sign_in_atDateTimeHolds the timestamp of the previous sign in
顧客最近一次登入時間 之前的登入時間 (倒數第二次登入的時間)
  • *UTC Time
2018-04-02T04:02:23.391+00:00
registered_atDateTimeCustomer register's Date and time
顧客註冊時間
  • *UTC Time
2018-01-10T06:33:45.231+00:00
registered_from_channel
(Only applied to O2O plan)
(O2O 商家適用)		ChannelRegistration Channel
會員實體註冊來源
created_byString顧客建立來源
“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
tagsArray or String自定義標籤["Tag A", "Tag B"]
tier_expires_atDateTimeMembership expiry date
會籍到期日
  • *UTC Time
"2021-12-18T15:59:59.999+00:00"
offline_referral_registered_atString門市綁定日期時間(只有使用 Smart OMO 服務的店家會有此欄位的值)
offline_referral_channel_idString門市 ID(只有使用 Smart OMO 服務的店家會有此欄位的值)
offline_referral_agent_idString門市推薦人 ID(只有使用 Smart OMO 服務的店家會有此欄位的值)
confirmed_atDateTimetimestamp of the email verification
顧客確認電郵注册時間
  • *UTC Time
2021-12-06T02:37:06.363+00:00
membership_tier_gapmembership_tier_gap entityNext membership tier's info
升到到下一會員等級所需的相關資訊
current_membership_tier_infocurrent_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_verifiedBooleanMobile Phone Verification Status
email_verifiedBooleanEmail Verification Status
unconfirmed_emailStringPending to verify Emailnil
customer_authentication_linkingsArray

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

FieldTypeDescriptionExample
next_tierMembershipTierInformation on the next membership tier.
下一個會員等級的資訊
  • Note最高階會員沒有 next tier（"next_tier": null）
next_discountFloatDiscount for the next membership tier.
下一個會員等級的折扣
  • 若沒有優惠則回傳 null
20
user_spendingNumberThe 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_extendNumberThe 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_spendingNumberThe amount of upgrading to next membership tier.
升等到下一會員等級所需之消費金額（Admin 設定的升級金額條件）
  • 若沒有下一級則回傳 null

5000

The number is same as cents in the currency

extend_total_spendingNumberThe 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

FieldTypeDescriptionExample
  • id
StringMembership tier's ID
會員等級ID		"66f27419fe4e57003f7017b6"
levelIntegerLevel of Current Membership Tier
等級高低		4
name_translationsobjectJson Object with key is the language code and value is the translation string
JSON 物件，鍵為語言代碼，值為對應的翻譯字串
  • {
    "zh-hant": "最高級別"
    }*
merchant_idStringMerchant ID"5e958a8f12743200434653fc"
member_countIntegerNumber of members in this membership tier
這個會員級別的會員人數		1
exclusive_product_countIntegerNumber of exlcusive products in this membership tier
這個會員級別不能購買的產品數目		0
promotion_countIntegerNumber of promotions in this membership tier
這個會員級別的優惠數目		1
member_discount_percentageNumber這個會員等級適用的折扣優惠40.0
valid_periodobjectValid period of this membership tier
這個會員級別的有效時段
  • {
    "type": "unlimited",
    "timevalue": "2",
    "time_unit": "month"
    }
membership_tier_rulesArrayRules 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_atDateTime"2024-09-24T08:11:05.029Z"
updated_atDateTime"2025-03-20T03:35:59.353Z"

Response Example

JSON sample

JSON example with mobile_phone without phones

Updated 6 months ago

Did this page help you?