--- title: "Get Customers" method: GET path: "/customers" tags: ["Customers"] --- # Get Customers `GET /customers` To get detailed information of couple customers sorted by time
利用時間範圍選取與排序獲取數筆顧客資料 ## Query parameters - `updated_after` string - `updated_before` string - `created_after` string - `created_before` string - `page` integer - `per_page` integer - `sort_by` 'asc' | 'desc' - `previous_id` string - `include_fields[]` string[] - `fields[]` string[] ## Response `200` OK - object - `items` Customer[] - `id` string — Customer Unique ID
顧客ID - `name` string, nullable — Customer Name
顧客姓名 - `email` string, nullable — Customer Email
顧客電子郵件 - `gender` 'male' | 'female' | 'other', nullable — Customer Gender
顧客性別 - `birthday` string, nullable — 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 日 - `birth_year` integer, nullable — Customer Birth Year
顧客出生年份
- `birth_month` integer, nullable — Customer Birth Month
顧客出生月份
- `birth_day` integer, nullable — Customer Birth Day
顧客出生日期
- `memo` string, nullable — Customer memo
顧客備註 - `phones` string[] — Customer Phones
顧客電話
-
*If customer mobile phone is confirmed, this field is hidden.
如果顧客手機已經確認,此欄位則會被隱藏 - `phone` string, nullable — Customer Phone
顧客電話
-
*If customer mobile phone is confirmed, this field is hidden.
如果顧客手機已經確認,此欄位則會被隱藏
This should be the last item in `phones` field.
此電話為 `phones` 欄位的最後一項 - `phone_country_code` string, nullable — Customer Phone Country Code
顧客電話國碼 - `mobile_phone` string, nullable — Customer Mobile Phone
顧客手機
-
*If customer mobile phone is confirmed, this field is displayed.
如果顧客手機已經確認,此欄位則會被顯示 - `mobile_phone_verified` boolean — Mobile Phone is Verified or not
是否手機驗證 - `mobile_phone_country_calling_code` string, nullable — Country Code of Mobile Phone
手機號碼國碼 - `locale_code` string, nullable — Customer Locale Code
顧客使用前台之語言 - `order_count` integer — Customer Order Number
顧客累積訂單數 - `orders_total_sum` object — Customer Orders Total Sum
顧客累積訂單資訊 - `cents` integer - `currency_symbol` string - `currency_iso` string - `label` string - `dollars` number - `is_member` boolean — Is the customer a member?
顧客是否為會員？ - `is_blacklisted` boolean — Is the customer in black-list?
顧客是否在黑名單？ - `is_subscribed_marketing_email` boolean — Does the customer subscribe marketing email?
顧客是否接受優惠宣傳？ - `credit_balance` integer — Current Customer Credits
顧客購物金餘額 - `member_point_balance` integer — Current Member Points
顧客會員點數餘額 - `custom_data` object[] - `type` string — Column Type for the Custom Field
欄位類別 - `name_translations` object — Name Translations
欄位名稱 - `en` string — Merchant defined English name
店家定義英文名稱 - `zh-hant` string — Merchant defined Traditional Chinese name
店家定義繁體中文名稱 - `zh-cn` string — Merchant defined Simplified Chinese name
店家定義簡體中文名稱 - `vi` string — Merchant defined Vietnamese name
店家定義越南文名稱 - `ms` string — Merchant defined Malaysian name
店家定義馬來西亞文名稱 - `ja` string — Merchant defined Japanese name
店家定義日文名稱 - `th` string — Merchant defined Thai name
店家定義泰文名稱 - `id` string — Merchant defined Indian name
店家定義印度文名稱 - `de` string — Merchant defined Deutsch name
店家定義德文名稱 - `fr` string — Merchant defined France name
店家定義法文名稱 - `field_id` string — Field ID
欄位ID - `value` string — Field Value
欄位值 - `membership_tier` object, nullable — Membership Tier Data
顧客會員等級 - `id` string — Membership tier's ID
會員等級ID - `level` integer — Level of Current Membership Tier
等級高低 - `name_translations` object — Name Translations
欄位名稱 - `en` string — Merchant defined English name
店家定義英文名稱 - `zh-hant` string — Merchant defined Traditional Chinese name
店家定義繁體中文名稱 - `zh-cn` string — Merchant defined Simplified Chinese name
店家定義簡體中文名稱 - `vi` string — Merchant defined Vietnamese name
店家定義越南文名稱 - `ms` string — Merchant defined Malaysian name
店家定義馬來西亞文名稱 - `ja` string — Merchant defined Japanese name
店家定義日文名稱 - `th` string — Merchant defined Thai name
店家定義泰文名稱 - `id` string — Merchant defined Indian name
店家定義印度文名稱 - `de` string — Merchant defined Deutsch name
店家定義德文名稱 - `fr` string — Merchant defined France name
店家定義法文名稱 - `status` string — Membership tier's status
會員等級狀態 - `delivery_addresses` OrderDeliveryAddress[] — Customer's Delivery Addresses
顧客送貨地址 - `country_code` string, nullable — Country Code
國家代碼 - `country` string, nullable — Country
國家 - `city` string, nullable — City
城市 - `district` string, nullable — City
地區 - `state` string, nullable — Stage or Region
州/省/地區 - `postcode` string, nullable — ZIP code
郵政編號 - `address_1` string, nullable — Address 1
地址 1 - `address_2` string, nullable — Address 1
地址 2
(這裡原則上會自動帶入地址所在行政區) - `key` string, nullable - `layer1` string, nullable - `layer2` string, nullable - `layer3` string, nullable - `logistic_codes` string[] - `recipient_name` string, nullable — Recipient Name
收件人姓名 - `recipient_phone` string, nullable — Recipient Phone
收件人電話號碼 - `recipient_phone_country_code` string, nullable — Recipient Phone Country Code
收件人電話號碼國碼 - `remarks` string, nullable — Remark
備註 - `subscribed_email_types` string[] — Subscribed Email Types
訂閱消息類型 - `ref_user_id` string, nullable — For third party to put custom user_id
可供儲存第三方顧客ID - `line_id` string, nullable — LINE ID
顧客Line ID - `facebook_id` string, nullable — FACEBOOK ID
顧客FACEBOOK ID - `google_id` string, nullable — GOOGLE ID
顧客GOOGLE ID - `updated_at` string — Customer Last Updated Time
顧客最後更新資訊時間
-
*UTC Time - `created_at` string — Customer Created Time
顧客資料創造時間
-
*UTC Time - `current_sign_in_at` string, nullable — Timestamp updated when customers sign in
顧客最後登入時間 - `last_sign_in_at` string, nullable — Holds the timestamp of the previous sign in
顧客上一次登入時間 - `registered_at` string, nullable — Customer register's Date and time
顧客註冊時間 - `registered_from_channel` object — Registration Channel
會員實體註冊來源 - `id` string - `name` object — Name Translations
名稱 - `en` string — Merchant defined English name
店家定義英文名稱 - `zh-hant` string — Merchant defined Traditional Chinese name
店家定義繁體中文名稱 - `zh-cn` string — Merchant defined Simplified Chinese name
店家定義簡體中文名稱 - `vi` string — Merchant defined Vietnamese name
店家定義越南文名稱 - `ms` string — Merchant defined Malaysian name
店家定義馬來西亞文名稱 - `ja` string — Merchant defined Japanese name
店家定義日文名稱 - `th` string — Merchant defined Thai name
店家定義泰文名稱 - `id` string — Merchant defined Indian name
店家定義印度文名稱 - `de` string — Merchant defined Deutsch name
店家定義德文名稱 - `fr` string — Merchant defined France name
店家定義法文名稱 - `platform` 'Shopee' | 'shop_crm' | 'online' | 'pos' | 'sc' — Shopee
shop_crm
online
pos
sc - `merchant_id` string - `updated_at` string - `created_at` string - `currency_code` string - `merchant_name` string - `default_warehouse_id` string - `identifier` string - `phones` object - `main` string - `address` object - `pin_codes` object[] - `code` string - `scope` string - `mobile_logo_media_url` string - `e_invoice_setting` object — only expose this object when the request_params include_fields contains e_invoice_setting value and the merchant of the channel has sl_pos_one_einvoice_setting rollout_key - `invoice_type` 'none' | 'tradevan' | 'cetustek' — invoice setting type - `invoice` object — only show this object when invoice_type is cetustek - `tax_id` string — 發票統一編號 - `source` object — merchant invoice information - `business_entity` string — 營業人名稱 - `invoice_tradevan` object — only show this object when invoice_type is tradevan - `tax_id` string — 發票統一編號 - `source` object — merchant invoice information - `business_entity` string — 營業人名稱 - `business_type_code` string — 事業別代號 - `created_by` 'shop' | 'admin' | 'openapi' | 'shop_crm' | 'pos' — 顧客建立來源
"shop" 來自前台網站
"admin" 來自後台
"openapi" 由open api創建
"shop_crm" 來自 kiosk
"pos"來自 POS - `created_by_channel` string, nullable — 顧客建立店家來源 - `tags` string[] — 自定義標籤 - `tier_expires_at` string, nullable — Membership expiry date
會籍到期日 - `confirmed_at` string, nullable — timestamp of the email verification
顧客確認電郵注册時間 - `utm_data` object — UTM Data
UTM參數 - `utm_source` string — UTM Source
標識哪個站點發送了流量，並且是必填參數。 - `utm_campaign` string — UTM Campaign
標識特定的產品促銷或戰略活動。 - `utm_medium` string — UTM Medium
標識所使用的鏈接類型，例如每次點擊或電子郵件的費用。 - `utm_content` string — UTM Content
標識用於將用戶帶到網站的具體操作，例如橫幅廣告或文本鏈接。 它通常用於A / B測試和以內容定位的廣告。
textlink
logolink - `utm_term` string — UTM Term
標識搜索詞。 - `utm_time` string — UTM Time - `referral_code` string, nullable — Referral code
推薦碼 - `offline_referral_registered_at` string, nullable — Referral Registered At
門市綁定時間 - `offline_referral_channel_id` string, nullable — Referral Channel ID
門市 ID - `offline_referral_agent_id` string, nullable — Referral Agent ID
門市推薦人 ID - `membership_tier_gap` object — Next membership tier's info
下一個會員等級的資料 - `next_tier` object — Membership Tier Data
顧客會員等級 - `id` string — Membership tier's ID
會員等級ID - `level` integer — Level of Current Membership Tier
等級高低
-
*Having higher level with larger number.
等級數越高，數字越大 - `name_translations` object — Name Translations
欄位名稱 - `en` string — Merchant defined English name
店家定義英文名稱 - `zh-hant` string — Merchant defined Traditional Chinese name
店家定義繁體中文名稱 - `zh-cn` string — Merchant defined Simplified Chinese name
店家定義簡體中文名稱 - `vi` string — Merchant defined Vietnamese name
店家定義越南文名稱 - `ms` string — Merchant defined Malaysian name
店家定義馬來西亞文名稱 - `ja` string — Merchant defined Japanese name
店家定義日文名稱 - `th` string — Merchant defined Thai name
店家定義泰文名稱 - `id` string — Merchant defined Indian name
店家定義印度文名稱 - `de` string — Merchant defined Deutsch name
店家定義德文名稱 - `fr` string — Merchant defined France name
店家定義法文名稱 - `membership_tier_rules` MembershipTierRule[] - `id` string — Membership tier rule's ID
會員等級規則ID - `effect_type` 'upgrade' | 'extend' — Type of the membership_tier_rule
會員級別規則的類別 - `condition_interval` object - `type` 'within_interval' | 'single_purchase' — Membership Upgrade Condition Type
會員升級條件類別
- within_interval: 指定期限內購物
- single_purchase: 單次購物 - `time_unit` 'month' — Membership Upgrade Condition Time Unit
會員升級條件時間單位 - `time_value` integer — Valid Period of the conditional interval if the type is "within_interval"
如類別是"within_interval"，升級條件時間的值 - `effect_interval` object - `type` 'within_interval' | 'unlimited' — Membership Valid Period
會員有效期限 - `time_unit` 'month' — Unit of Valid Period
有效期限單位 - `time_value` integer — Valid Period of the effect interval if the type is "within_interval"
如類別是"within_interval"，有效期間的值 - `total_spending` object - `cents` integer — Total Spending Requirement represent in cents
以仙為單位表示總消費要求 - `currency_symbol` string — Total Spending Requirement represent in currency_symbol
以currency_symbol表示總消費要求 - `currency_iso` string — Total Spending Requirement represent in currency_iso
以currency_iso表示總消費要求 - `label` string — Total Spending Requirement represent in label
以標籤表示總消費要求 - `dollars` number, float — Total Spending Requirement represent in dollars
以元為單位表示總消費要求 - `created_at` string — The timestamp that the rule is created at
規則創造時間 - `updated_at` string — The timestamp that the rule is updated at
規則更新時間 - `next_discount` number, float — The discount of next membership tier
下一個會員等級的折扣優惠 - `user_spending` number, float — 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。
- `user_spendings_for_extend` number, float — 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。
- `next_total_spending` number, float — The amount of upgrading to next membership tier.
升等到下一會員等級所需之消費金額（Admin 設定的升級金額條件）
*若沒有下一級則回傳 null - `extend_total_spending` number, float — The amount of extending in current membership tier.
續會目前會員等級所需之消費金額（Admin 設定的續會金額條件）
*若沒有設定則回傳 null - `current_membership_tier_info` object — Current membership tier's info
現時的會員等級的資料 - `_id` string — Membership tier's ID
會員等級ID - `level` integer — Level of Current Membership Tier
等級高低 - `name_translations` object — Name Translations
欄位名稱 - `en` string — Merchant defined English name
店家定義英文名稱 - `zh-hant` string — Merchant defined Traditional Chinese name
店家定義繁體中文名稱 - `zh-cn` string — Merchant defined Simplified Chinese name
店家定義簡體中文名稱 - `vi` string — Merchant defined Vietnamese name
店家定義越南文名稱 - `ms` string — Merchant defined Malaysian name
店家定義馬來西亞文名稱 - `ja` string — Merchant defined Japanese name
店家定義日文名稱 - `th` string — Merchant defined Thai name
店家定義泰文名稱 - `id` string — Merchant defined Indian name
店家定義印度文名稱 - `de` string — Merchant defined Deutsch name
店家定義德文名稱 - `fr` string — Merchant defined France name
店家定義法文名稱 - `merchant_id` string — merchant ID - `exclusive_product_count` integer — Number of exlcusive products in this membership tier
這個會員級別不能購買的產品數目 - `promotion_count` integer — Number of promotions in this membership tier
這個會員級別的優惠數目 - `valid_period` object — Valid period of this membership tier
這個會員級別的有效時段 - `type` string — Type
種類 - `time_unit` string — Time unit
時間單位 - `time_value` string — Time value
時間值 - `membership_tier_rules` MembershipTierRule[] - `id` string — Membership tier rule's ID
會員等級規則ID - `effect_type` 'upgrade' | 'extend' — Type of the membership_tier_rule
會員級別規則的類別 - `condition_interval` object - `type` 'within_interval' | 'single_purchase' — Membership Upgrade Condition Type
會員升級條件類別
- within_interval: 指定期限內購物
- single_purchase: 單次購物 - `time_unit` 'month' — Membership Upgrade Condition Time Unit
會員升級條件時間單位 - `time_value` integer — Valid Period of the conditional interval if the type is "within_interval"
如類別是"within_interval"，升級條件時間的值 - `effect_interval` object - `type` 'within_interval' | 'unlimited' — Membership Valid Period
會員有效期限 - `time_unit` 'month' — Unit of Valid Period
有效期限單位 - `time_value` integer — Valid Period of the effect interval if the type is "within_interval"
如類別是"within_interval"，有效期間的值 - `total_spending` object - `cents` integer — Total Spending Requirement represent in cents
以仙為單位表示總消費要求 - `currency_symbol` string — Total Spending Requirement represent in currency_symbol
以currency_symbol表示總消費要求 - `currency_iso` string — Total Spending Requirement represent in currency_iso
以currency_iso表示總消費要求 - `label` string — Total Spending Requirement represent in label
以標籤表示總消費要求 - `dollars` number, float — Total Spending Requirement represent in dollars
以元為單位表示總消費要求 - `created_at` string — The timestamp that the rule is created at
規則創造時間 - `updated_at` string — The timestamp that the rule is updated at
規則更新時間 - `created_at` string - `updated_at` string - `metafields` object — metafields
only show if include_fields[]=metafields - `customer_authentication_linkings` string[] — 3rd Party Customer Authentication（SSO）
SSO 第三方串接相關資訊

* 備註：串接 SSO 的會員 ID 不會存在 ref_user_id，會存在 customer_authentication_linkings 中的 ref_id - `subscriptions` object[] — Subscriptions
*SMS subscription is an async operation
, so the field might not show the result immediately - `is_active` boolean - `platform` string - `orders_totals` object[] - `id` string — Order ID
訂單ID - `total` object — The total amount of the order
訂單總額 - `cents` integer - `currency_symbol` string - `currency_iso` string - `label` string - `dollars` number - `platform` string — The platform that creates the order
創建此訂單的平台 - `member_info_reward` object — Member Info Reward
會員資料獎賞

If a customer has not yet filled out the relevant fields of information but qualifies for a data reward, the reward content and fields will be returned.
如果顧客尚未填寫相關欄位的資料，且顧客符合資料獎賞的資格則會返回獎賞內容及欄位。

only show if include_fields[]=member_info_reward of GET customer API
只有在 GET customer API 中 include_fields[]=member_info_reward 時才會顯示 - `custom_fields` unknown[] — Custom fields that qualify for data rewards will be recognized.
會認列資料獎賞的自定義欄位 - unknown - `reward_on` unknown[] — The fields that qualify for data rewards will be recognized.
會認列資料獎賞的基本欄位 - unknown - `promotion_ids` unknown[] — The promotion IDs of the rewards.
獎賞的 promotion IDs

If the merchant did not choose to offer a promotion reward, it will be null.
如果店家沒有選擇提供優惠獎賞，則為 null - unknown - `user_credits` integer — The user credits of the rewards.
獎賞的購物金

If the merchant did not choose to offer a shopping credit reward, it will be null.
如果店家沒有選擇提供購物金獎賞，則為 null - `member_points` integer — The member points of the rewards.
獎賞的會員點數

If the merchant did not choose to offer a member point reward, it will be null.
如果店家沒有選擇提供會員點數獎賞，則為 null - `info_reward_triggered` boolean — If the Update Customer API is called to update customer information and triggers the sending of a customer data reward, it will be true.
如果呼叫 Update Customer API 更新顧客資料並觸發發送顧客資料獎賞，則為 true - `info_reward_claimed` boolean — Whether the customer has claimed the info reward
顧客是否已經領取資料獎賞 - `pagination` Paginatable - `current_page` integer — The current page number
當前分頁 - `per_page` integer — Number of result per page
每頁顯示 n 筆資料
(Default: 24) - `total_count` integer — Number of result in total
資料總量 - `total_pages` integer — Number of pages in total
總頁數量 ## Other responses - `401` — Bad authentication - `403` — Forbidden - `422` — Unprocessable entity error - `500` — Server error --- [API](https://skmtc.net/shoplineapp/apis/shopline-open-api.md) · [All operations](https://skmtc.net/shoplineapp/apis/shopline-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shoplineapp/shopline-open-api/revisions/1675ac12cde7/schema)