Create a customer

Requires write_customers access scope.
For more info, refer to:
access permission.
POST https://{handle}.myshopline.com/admin/openapi/v20260301/customers.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 .
Create a new customer in the store. You need to provide detailed information such as the customer's email or mobile phone number.
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
Request Body
  • customerobject
    Customer Information.
  • accepts_marketing boolean
    Whether the customer accepts to subscribe to marketing information via email. The customer's email address is required when modifying the subscription status.
    DEPRECATED: This parameter is deprecated from API version v20250601.
    Example: true
  • addressesobject[]
    Customer address list.
    Maximum size: 50
  • address1 string
    Customer address information such as the street address or a post office box number.
    Maximum length: 255
    Example: 7720 Cherokee Road
  • address2 string
    The second line of the address. This typically includes information such as apartment, suite, or unit number.
    Maximum length: 255
    Example: Apartment 2
  • city string
    The city in the address.
    Maximum length: 64
    Example: Hagerman
  • company string
    The company name.
    Maximum length: 255
    Example: Joy
  • country string
    The country or region in the address.
    Maximum length: 64
    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.
    Example: US
  • country_name string
    Standardized country or region name in addresses.
    DEPRECATED: This parameter is deprecated from API version v20250601.
    Example: United States
  • default boolean
    Whether the address is set as the default address. Valid values are:
    • true: The default address
    • false: Not the default address
    Default value: false
    Example: true
  • first_name string
    The customer's first name.
    Maximum length: 128
    Example: Bob
  • last_name string
    The customer's last name.
    Maximum length: 128
    Example: Norman
  • name string
    The customer's nickname.
    DEPRECATED: This parameter is deprecated from API version v20250601.
    Example: NormanBob
  • phone string
    The customer's mobile phone number.
    Maximum length: 20
    Example: 001467326483
  • province string
    The province in the address.
    Maximum length: 64
    Example: Kentucky
  • province_code string
    The code for the province in the address, which can be a custom code or a two-digit ISO 3166-2 international code.
    Example: KY
  • zip string
    The postal code information of the address.
    Maximum length: 64
    Example: 40202
  • birthday string
    Customer's birthday. Format: yyyyMMdd.
    Example: 20210831
    Example: 19970102
  • email string
    Customer's email.
    Maximum length: 50
    Example: gungcherny@gamil.com
  • email_marketing_consentobject
    Email marketing subscription information.
  • consent_collected_from string
    Subscription information source.
    Maximum length: 50
  • consent_updated_at string
    The date and time when the subscription was updated. Format: ISO 8601.
    Example: 2024-08-31T02:20:26+08:00
    Example: 2022-09-07T10:53:31+08:00
  • opt_in_level integer
    Subscription method. Valid values are:
    • 0 : unknown
    • 1 : single opt-in
    • 2 : confirmed opt-in
    The default value depends on whether the Marketing options setting is enabled in the SHOPLINE Admin.
    • Enabled: Default value is 2.
    • Disabled: Default value is 1.
    Example: 1
  • state integer
    Email subscription status. Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
    • 3 : Awaiting confirmation
    This field must be passed when any other subfields under email_marketing_consent have values.
    Example: 1
  • first_name string
    The customer's first name.
    Maximum length: 128
    Example: Bob
  • gender integer
    Customer's gender. Valid values are:
    • 0 : unknown
    • 1 : male
    • 2 : female
    • 3 : secret
    Default value: 0
    Example: 1
  • last_name string
    The customer's last name.
    Maximum length: 128
    Example: Norman
  • multipass_identifier string
    A unique identifier for the customer that logs in with Multipass login.
    Maximum length: 100
  • note string
    Merchant's notes on the customer.
    Maximum length: 1000
    Example: Placed an order that had a fraud warning
  • password string
    Customer's password. If it is passed in, the customer state changes from “not invited” to “registered”. The customer state is represented by the customer.state in the response.
    Password length: 6-18 characters
    Allowed characters: uppercase letters, lowercase letters, numbers, and symbols
    Example: 31233
  • password_confirmation string
    The customer's second password input for confirmation.
    Password length: 6-18 characters
    Allowed characters: uppercase letters, lowercase letters, numbers, and symbols
    Example: 31233
  • phone string
    The customer's mobile phone number.
    Maximum length: 20
    Example: 001467326483
  • sms_marketing_consentobject
    SMS marketing subscription information.
  • consent_collected_from string
    Subscription information source.
    Maximum length: 50
  • consent_updated_at string
    The date and time when the subscription was updated. Format: ISO 8601.
    Example: 2024-08-31T02:20:26+08:00
    Example: 2022-09-07T10:53:31+08:00
  • opt_in_level integer
    Subscription method. Valid values are:
    • 0 : unknown
    • 1 : single opt-in
    • 2 : confirmed opt-in
    Example: 1
  • state integer
    SMS subscription status. Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
    This field must be passed when any other subfields under sms_marketing_consent have values.
    Example: 1
  • tags string
    Add tags for customers, separating different tags with commas.
    Maximum number of tags allowed: 100
    Maximum length per tag: 128
    Maximum length total: 1000
    Example: loyal
  • verified_email boolean
    Whether the email has been verified. Valid values are:
    • true : verified
    • false : unverified
    Default value: false
    Example: true
Status Codes
For the complete list of codes and messages, see Http status code.
Response Headers
  • 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
  • customerobject
    Customer information.
  • accepts_marketing boolean
    Whether the customer accepts to subscribe to marketing information via email. The customer's email address is required when modifying the subscription status.
    DEPRECATED: This parameter is deprecated from API version v20250601.
    Example: true
  • accepts_marketing_updated_at string
    The time when the customer renewed their subscription to email marketing.
    DEPRECATED: This parameter is deprecated from API version v20250601.
    Example: 2022-05-31T15:32:46+08:00
  • 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.
    Example: true
  • 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.
    Example: 2022-05-31T15:32:46+08:00
  • addressesobject[]
    Customer address list.
  • address1 string
    Customer address 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.
    Example: Joy
  • 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 customer.
    Example: 4201825054
  • default boolean
    Whether the address is set as the default address. Valid values are:
    • true: Default address.
    • false: No default address.
    Example: true
  • first_name string
    The customer's first name.
    Example: Bob
  • id string
    The unique identifier for the addresses.
    Example: 207119551
  • last_name string
    The customer's last name.
    Example: Norman
  • phone string
    The customer's mobile phone number.
    Example: 001467326483
  • province string
    The province in the address.
    Example: Kentucky
  • province_code string
    The code for the province in the address, which can be a custom code or a two-digit ISO 3166-2 international code.
    DEPRECATED: This parameter is deprecated from API version v20250601
    Example: KY
  • province_code_v2 string
    The code for the province in the address, which can be a custom code or a two-digit ISO 3166-2 international code.
    Example: KY
  • zip string
    The postal code information of the address.
    Example: 40202
  • asid string
    The unique identifier for the facebook login.
    Example: 481007156599455
  • birthday string
    Customer's birthday.
    Example: 19970102
  • created_at string
    The data and time when the customer was created.
    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
    Customer address 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.
    Example: Joy
  • 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 customer.
    Example: 4201825054
  • default boolean
    Whether the address is set as the default address.
    Example: true
  • first_name string
    The customer's first name.
    Example: Bob
  • id string
    The unique identifier for the addresses.
    Example: 207119551
  • last_name string
    The customer's last name.
    Example: Norman
  • phone string
    The customer's mobile phone number.
    Example: 001467326483
  • province string
    The province in the address.
    Example: Kentucky
  • province_code string
    The code for the province in the address, which can be a custom code or a two-digit ISO 3166-2 international code.
    DEPRECATED: This parameter is deprecated from API version v20250601
    Example: KY
  • province_code_v2 string
    The code for the province in the address, which can be a custom code or a two-digit ISO 3166-2 international code.
  • zip string
    The postal code information of the address.
    Example: 40202
  • email string
    Customer's email.
    Example: gungcherny@gamil.com
  • email_marketing_consentobject
    Email marketing subscription information.
  • consent_collected_from string
    Subscription information source.
  • consent_updated_at string
    The date and time when the subscription was updated. Format: ISO 8601.
    Example: 2022-09-07T10:53:31+08:00
  • opt_in_level integer
    Subscription method. Valid values are:
    • 0 : unknown
    • 1 : single opt-in
    • 2 : confirmed opt-in
    Example: 1
  • state integer
    Email subscription status. Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
    • 3 : Awaiting confirmation
    Example: 1
  • email_subscribe_flag integer
    The final subscription status of the customer's email. Returned based on the email_marketing_consent related input information. Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
    Example: 1
  • first_name string
    The customer's first name.
    Example: Bob
  • gender string
    Customer's gender. Valid values are:
    • others : unknown
    • male : male
    • female : female
    • secret : secret
    Example: female
  • id string
    The customer's unique ID .
    Example: 4201825054
  • language string
    Customer language.
    Example: en
  • last_name string
    The customer's last name.
    Example: Norman
  • last_order_id string
    The unique identifier for the customer's last recent order.
    Example: 2005473211984312275741
  • last_order_name string
    The most recent custom order number.
    Example: #20269M
  • mobile_subscribe_flag integer
    The final subscription status of the customer's mobile phone number. Returned based on the sms_marketing_consent related input information. 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.
  • note string
    Merchant's notes on the customer.
    Example: Placed an order that had a fraud warning
  • orders_count long
    The order quantity by the customer.
    Example: 12
  • phone string
    The customer's mobile phone number.
    Example: 001467326483
  • sms_marketing_consentobject
    SMS marketing subscription information.
  • consent_collected_from string
    Subscription information source.
  • consent_updated_at string
    The date and time when the subscription was updated. Format: ISO 8601.
    Example: 2022-09-07T10:53:31+08:00
  • opt_in_level integer
    Subscription method. Valid values are:
    • 0 : unknown
    • 1 : single opt in
    • 2 : confirmed opt in
    Example: 1
  • state integer
    SMS subscription status. Valid values are:
    • 0 : Unsubscribed
    • 1 : Subscribed
    • 2 : Not subscribed
    • 3 : Awaiting confirmation
    Example: 1
  • social_customer array
    The customer's unique ID on social media.
    DEPRECATED: This parameter is deprecated from API version v20250601
    Example: ["[6612273988815231]"]
  • state integer
    Customer's status. Valid values are:
    • 0: Blacklist
    • 1: Not invited
    • 2: Invited
    • 3: Registered
    Example: 2
  • tags string
    Customer's tags.
    Example: loyal
  • total_spent string
    Total amount spent by the customer.
    Example: 100
  • updated_at string
    Customer update time. Format: ISO 8601.
    Example: 2022-09-07T10:53:31+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

Body

required
{
  "customer": {
    "accepts_marketing": true,
    "addresses": [
      {
        "address1": "7720 Cherokee Road",
        "address2": "Apartment 2",
        "city": "Hagerman",
        "company": "Joy",
        "country": "United States",
        "country_code": "US",
        "country_name": "United States",
        "default": true,
        "first_name": "Bob",
        "last_name": "Norman",
        "name": "NormanBob",
        "phone": "001467326483",
        "province": "Kentucky",
        "province_code": "KY",
        "zip": "40202"
      }
    ],
    "birthday": "19970102",
    "email": "gungcherny@gamil.com",
    "email_marketing_consent": {
      "consent_collected_from": null,
      "consent_updated_at": "2022-09-07T10:53:31+08:00",
      "opt_in_level": 1,
      "state": 1
    },
    "first_name": "Bob",
    "gender": 1,
    "last_name": "Norman",
    "multipass_identifier": null,
    "note": "Placed an order that had a fraud warning",
    "password": "31233",
    "password_confirmation": "31233",
    "phone": "001467326483",
    "sms_marketing_consent": {
      "consent_collected_from": null,
      "consent_updated_at": "2022-09-07T10:53:31+08:00",
      "opt_in_level": 1,
      "state": 1
    },
    "tags": "loyal",
    "verified_email": true
  }
}

Language

curl --request POST \
     --url https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301/customers.json \
     --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw' \
     --header 'Content-Type: application/json; charset=utf-8' \
     --header 'accept: application/json'
Examples
Create a customer
Request
{
  "customer": {
    "addresses": [
      {
        "address1": "Pas************-31A",
        "address2": "",
        "city": "Ma******ss",
        "company": "Shopline",
        "country": "Singapore",
        "country_code": "SG",
        "default": "true",
        "first_name": "D****",
        "last_name": "B****",
        "phone": "008********5656",
        "province": "",
        "province_code": "",
        "zip": "*****40"
      }
    ],
    "birthday": "20210831",
    "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
    },
    "first_name": "D****",
    "gender": "3",
    "last_name": "B****",
    "multipass_identifier": "",
    "note": "shopline notes",
    "password": "****56",
    "password_confirmation": "****56",
    "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
    },
    "tags": "DemoTag1,DemoTag2",
    "verified_email": true
  }
}
Response
{
  "customer": {
    "accepts_marketing": true,
    "accepts_marketing_updated_at": "2021-08-31T02:20:26+08:00",
    "accepts_mobile_marketing": true,
    "accepts_mobile_marketing_updated_at": "2021-08-31T02:20:26+08:00",
    "addresses": [
      {
        "address1": "Pas************-31A",
        "address2": "",
        "city": "Ma******ss",
        "company": "Shopline",
        "country": "Singapore",
        "country_code": "SG",
        "customer_id": "*******882",
        "default": true,
        "first_name": "D****",
        "id": "******************82651722",
        "last_name": "B****",
        "phone": "008********5656",
        "province": "",
        "province_code": "",
        "province_code_v2": "",
        "zip": "*****40"
      }
    ],
    "asid": null,
    "birthday": "20210831",
    "created_at": "2025-02-19T18:02:29+08:00",
    "currency": "USD",
    "default_address": {
      "address1": "Pas************-31A",
      "address2": "",
      "city": "Ma******ss",
      "company": "Shopline",
      "country": "Singapore",
      "country_code": "SG",
      "customer_id": "*******882",
      "default": true,
      "first_name": "D****",
      "id": "******************82651722",
      "last_name": "B****",
      "phone": "008********5656",
      "province": "",
      "province_code": "",
      "province_code_v2": "",
      "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****",
    "gender": "secret",
    "id": "*******882",
    "language": null,
    "last_name": "B****",
    "last_order_id": null,
    "last_order_name": null,
    "mobile_subscribe_flag": 1,
    "multipass_identifier": "",
    "note": "shopline notes",
    "orders_count": null,
    "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
    },
    "social_customer": null,
    "state": null,
    "tags": "DemoTag1,DemoTag2",
    "total_spent": "0",
    "updated_at": "2025-02-19T18:02:30+08:00",
    "verified_email": null
  }
}
Was this article helpful to you?
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
Legal
Privacy
Terms
Developer Agreement
LinkedInEmail
LinkedInEmail
© Copyright 2013-2025 SHOPLINE Limited.