Search for customers

Requires read_customers access scope.
For more info, refer to:
access permission.
GET https://{handle}.myshopline.com/admin/openapi/v20260301/customers/v2/search.json
handle : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is open001.myshopline.com , the store handle is open001 .
Search for customers using specified criteria. You can perform a fuzzy search by customer email or name, or query customer information based on conditions such as subscription status.
Query Parameters
  • fields string
    Specify the fields to be returned, with multiple fields separated by commas. For available fields, refer to the top-level child parameters under the customers object in the response.
    Example: id,email,first_name
  • limit string
    Specify the maximum number of customers to return.
    Value range: 1-250
    Default value: 50
  • order string
    Determines the sort order for customer data. Valid values are:
    • 0: Sort by customer creation time in descending order.
    • 1: Sort by customer creation time in descending order. If creation times are identical, sort by the most recent order time in descending order.
    • 2: Sort by customer creation time in descending order. If creation times are identical, sort by the order quantity in descending order.
    • 3: Sort by customer creation time in descending order. If creation times are identical, sort by customer ID in descending order.
    Default value: 0
  • page_info string
    The unique identifier for pagination queries, used to locate a specific page.
    This parameter value is obtained from the link value in the response header of this API after you have queried the pagination information.
    For example, if the link value you obtained is <https://{handle}.myshopline.com/admin/openapi/{version}/customers/v2/search.json?limit=1&page_info=eyJzaW5jZUlkIjoiMTYwNTc1OTAxNTM4OTA4Mjk1MjExMTI3ODgiLCJkaXJlY3Rpb24iOiJuZXh0IiwibGltaXQiOjF9>; rel="next" , the value of page_info is eyJzaW5jZUlkIjoiMTYwNTc1OTAxNTM4OTA4Mjk1MjExMTI3ODgiLCJkaXJlY3Rpb24iOiJuZXh0IiwibGltaXQiOjF9 .
    For more information on how to use pagination, refer to Paging Mechanism.
  • query string
    The query criteria. You can query data based on the following fields: accepts_marketing，email_subscribe_flag，customer_date，customer_first_name，customer_id，tags，orders_count，order_date，state，total_spent，updated_at，and verified_email. Refer to the response body for the meaning of each field.
    Syntax rules:
    • Separate multiple fields with a semicolon.
    • Separate each field and its value with a colon.
    Example: customer_id:1;orders_count:2
  • query_param string
    Fuzzy query conditions. You can query data based on the following fields: phone,email，first_name,last_name,address1,address2. Refer to the response body for the meaning of each field.
    Maximum length: 50
    Example: bob
Request Headers
  • Content-Type string required
    The field must be set to the fixed value application/json; charset=utf-8.
  • Authorization string required
    The access token for the API resource. Refer to App authorization to obtain the access token, and then pass the obtained token in the Bearer format.
    Example:
    Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw
Status Codes
For the complete list of codes and messages, see Http status code.
Response Headers
  • link
    The URL link that provides the pagination data. You can obtain page_info from this parameter for subsequent pagination requests.
    This parameter is returned when the requested page has a previous or next page.
    For more information on how to use pagination, refer to Paging Mechanism.
  • traceId
    A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise.
Response Body
  • customersobject[]
    A list of customers.
  • accepts_marketing boolean
    Whether the customer accepts to subscribe to marketing information via email.
    DEPRECATED: This parameter is deprecated from API version v20250601.
  • accepts_marketing_updated_at string
    The time when the customer updated their subscription to email marketing.
    DEPRECATED: This parameter is deprecated from API version v20250601.
  • accepts_mobile_marketing boolean
    Whether the customer accepts to subscribe to marketing information via mobile phone number.
    DEPRECATED：This parameter is deprecated from API version v20250601.
  • accepts_mobile_marketing_updated_at string
    The time when the customer updated his subscription to mobile phone number marketing.
    This parameter is deprecated from API version v20250601.
  • addressesobject[]
    A list of customer addresses.
  • address1 string
    The first line of the customer's address. This typically includes information such as the street address or a post office box number.
    Example: 7720 Cherokee Road
  • address2 string
    The second line of the customer's address. This typically includes information such as apartment, suite, or unit number.
    Example: Apartment 2
  • city string
    The city in the address.
  • company string
    The company name.
  • country string
    The country or region in the address.
    Example: United States
  • country_code string
    A two-letter country or region code that follows the ISO 3611-1 (alpha 2) standard, used to identify a specific country or region in the address.
  • customer_id string
    The unique identifier for the customer.
  • default boolean
    Whether the address is set as the default address. Valid values are:
    • true: Default address.
    • false: No default address.
  • first_name string
    The first name of the customer.
    Example: Bob
  • id string
    The unique identifier for the address.
  • last_name string
    The last name of the customer.
    Example: Norman
  • phone string
    The phone number of the customer.
    Example: 001123-***-7890
  • province string
    The province in the address.
    Example: Kentucky
  • province_code string
    The custom code for the province in the address.
    DEPRECATED: This parameter is deprecated from API version v20250601
  • province_code_v2 string
    The code for the province in the address, which is a two-digit ISO 3166-2 international code.
    Example: KY
  • zip string
    The postal code information of the address.
  • asid string
    The unique identifier for the Facebook login.
  • birthday string
    The birthday of the customer. Format: yyyyMMdd.
    Example: 19970102
  • created_at string
    The data and time when the customer was created. Format: ISO 8601.
    Example: 2022-09-07T10:53:31+08:00
  • currency string
    The currency used by the customer to place an order. The value of this parameter is a three-letter currency code that follows the ISO 4217 standard.
    Example: USD
  • default_addressobject
    Default address.
  • address1 string
    The first line of the customer's address. This typically includes information such as the street address or a post office box number.
    Example: 7720 Cherokee Road
  • address2 string
    The second line of the address. This typically includes information such as apartment, suite, or unit number.
    Example: Apartment 2
  • city string
    The city in the address.
    Example: Hagerman
  • company string
    The company name.
  • country string
    The country or region in the address.
    Example: United States
  • country_code string
    A two-letter country or region code that follows the ISO 3611-1 (alpha 2) standard, used to identify a specific country or region in the address.
    Example: US
  • customer_id string
    The unique identifier for the customer.
  • default boolean
    Always returns true, indicating that the address is set as the default address.
  • first_name string
    The first name of the customer.
    Example: Bob
  • id string
    The unique identifier for the address.
  • last_name string
    The last name of the customer.
    Example: Norman
  • phone string
    The phone number of the customer.
    Example: 001123-***-7890
  • province string
    The province in the address.
    Example: Kentucky
  • province_code string
    The custom code for the province in the address.
    DEPRECATED: This parameter is deprecated from API version v20250601
  • province_code_v2 string
    The code for the province in the address, which is a two-digit ISO 3166-2 international code.
    Example: KY
  • zip string
    The postal code information of the address.
    Example: 40202
  • email string
    The email of the customer.
    Example: *********@example.com
  • email_marketing_consentobject
    Email marketing subscription information.
  • consent_collected_from string
    Subscription information source.
    Example: Pop
  • consent_updated_at string
    The date and time when the subscription was updated. Format: ISO 8601.
  • opt_in_level integer
    Subscription method. Valid values are:
    • 0 : unknown
    • 1 : single opt-in
    • 2 : confirmed opt-in
  • state integer
    Email subscription status. Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
    • 3 : Awaiting confirmation
  • email_subscribe_flag integer
    The final subscription status of the customer's mobile phone number. Returned based on the email_marketing_consent input when creating or updating a customer. Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
  • first_name string
    The first name of the customer.
  • gender string
    The gender of the customer. Valid values are:
    • 0 : unknown
    • 1 : male
    • 2 : female
  • id string
    The unique identifier for the customer.
  • language string
    The language used by the customer.
  • last_name string
    The last name of the customer.
    Example: Norman
  • last_order_id string
    The unique identifier for the most recent order.
  • last_order_name string
    The custom number for the most recent order.
  • mobile_subscribe_flag integer
    The final subscription status of the customer's mobile phone number. Returned based on the sms_marketing_consent input when creating or updating a customer. Valid values are:
    • 0: Unsubscribed
    • 1: Subscribed
    • 2: Not subscribed
  • multipass_identifier string
    A unique identifier for the customer that's used with Multipass login.
  • nick_name string
    The nickname of the customer.
  • note string
    Merchant's notes on the customer.
  • orders_count long
    The number of orders placed by the customer.
  • phone string
    The phone number of the customer.
    Example: 001123-***-7890
  • sms_marketing_consentobject
    SMS marketing subscription information.
  • consent_collected_from string
    Subscription information source.
    Example: Pop
  • consent_updated_at string
    The date and time when the subscription was updated. Format: ISO 8601.
    Example: 2021-08-31T02:20:26+08:00
  • opt_in_level integer
    Subscription method. Valid values are:
    • 0 : unknown
    • 1 : single opt-in
    • 2 : confirmed opt-in
  • state integer
    Subscription method.Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
    • 3 : Awaiting confirmation
  • social_customer array
    The customer's unique ID on social media.
    DEPRECATED: This parameter is deprecated from API version v20250601
  • state integer
    The status of the customer. Valid values are:
    • 0: Blacklist
    • 1: Not invited
    • 2: Invited
    • 3: Registered
  • tags string
    The tags of the customer.
  • total_spent string
    Total amount spent by the customer, displayed in the store currency.
  • updated_at string
    The date and time when the customer was updated. Format: ISO 8601.
    Example: 2024-08-31T02:20:26+08:00
  • verified_email boolean
    Whether the email has been verified. Valid values are:
    • true : verified
    • false : unverified
API Explorer
https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301

ParamOptions

— header required
— query
— query
— query
— query
— query
— query

Language

curl --request GET \
     --url https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301/customers/v2/search.json \
     --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw' \
     --header 'Content-Type: application/json; charset=utf-8' \
     --header 'accept: application/json'
Examples
Perform a fuzzy search for customers
Response
{
  "customers": [
    {
      "accepts_marketing": true,
      "accepts_marketing_updated_at": "2021-08-31T02:20:26+08:00",
      "accepts_mobile_marketing_updated_at": "2021-08-31T02:20:26+08:00",
      "accepts_phone_marketing": true,
      "addresses": [
        {
          "address1": "Pas************-31A",
          "address2": "",
          "city": "Ma******ss",
          "company": "Shopline",
          "country": "Singapore",
          "country_code": "SG",
          "customer_id": "*******021",
          "default": true,
          "first_name": "D****",
          "id": "******************82651722",
          "last_name": "B****",
          "phone": "008********5656",
          "province": "",
          "province_code": "",
          "province_code_v2": "",
          "zip": "*****40"
        }
      ],
      "asid": null,
      "created_at": "2021-08-31T02:20:26+08:00",
      "currency": "USD",
      "default_address": {
        "address1": "Pas************-31A",
        "address2": "",
        "city": "Ma******ss",
        "company": "Shopline",
        "country": "Singapore",
        "country_code": "SG",
        "customer_id": "*******021",
        "default": true,
        "first_name": "D****",
        "id": "******************82651722",
        "last_name": "B****",
        "phone": "008********5656",
        "province": "",
        "province_code": "",
        "province_code_v2": null,
        "zip": "*****40"
      },
      "email": "*********@example.com",
      "email_marketing_consent": {
        "consent_collected_from": "shopline",
        "consent_updated_at": "2021-08-31T02:20:26+08:00",
        "opt_in_level": 1,
        "state": 1
      },
      "email_subscribe_flag": 1,
      "first_name": "D****",
      "id": "*******021",
      "last_name": "B****",
      "last_order_id": null,
      "last_order_name": null,
      "mobile_subscribe_flag": 1,
      "multipass_identifier": "",
      "note": "shopline notes",
      "orders_count": 0,
      "phone": "008********5656",
      "sms_marketing_consent": {
        "consent_collected_from": "shopline",
        "consent_updated_at": "2021-08-31T02:20:26+08:00",
        "opt_in_level": 1,
        "state": 1
      },
      "state": 3,
      "tags": null,
      "total_spent": "0",
      "updated_at": "2021-08-31T02:20:26+08:00",
      "verified_email": true
    }
  ]
}
Was this article helpful to you?
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
Legal
Privacy
Terms
Developer Agreement
LinkedInEmail
LinkedInEmail
© Copyright 2013-2025 SHOPLINE Limited.