Docs
Management API
Customers V2

Customers V2

Create and Manage Customers, Customer Addresses, and Customer Groups. Additionally, validate customer passwords. To learn more about Customers see the Customers Overview.

Available Endpoints

Resource / EndpointDescription
CustomersIdentity and account details for customers shopping on BigCommerce stores
Customers AddressesPostal address belonging to a customer
Customers GroupsGroupings of customers who share the same level of access and discounts
Customers Validate PasswordValidate customer passwords

Usage Notes

Customer Groups

  • Customer Groups are only available on specific plans.

Customers vs. Subscribers

  • A subscriber is not always a customer. Someone can sign up for the newsletter only and not create an account.
  • A customer is not always a subscriber. Signing up for the newsletter is a separate action from creating an account and purchasing an item.
  • A customer and a subscriber can be the same. If a shopper checks out on the storefront, creates an account and opts into the newsletter, they are a customer and a subscriber.

Resources

Related APIs / Endpoints

Webhooks

Get All Customers

GET /customers
⚠️
This endpoint is deprecated.

Request

Returns a list of all Customers. Default sorting is by customer_ID, from lowest to highest. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • first_name in query - string
  • last_name in query - string
  • company in query - string
  • email in query - string
  • phone in query - string
  • store_credit in query - string
  • customer_group_id in query - integer
  • min_id in query - integer
  • max_id in query - integer
  • min_date_created in query - string
  • max_date_created in query - string
  • min_date_modified in query - string
  • max_date_modified in query - string
  • tax_exempt_category in query - string

example

Response

Body

array | application/json

  • id    integer
    read-only

    Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

    Example: 1

  • date_created    string
    read-only

    Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • date_modified    string
    read-only

    Date on which the customer updated their details in the storefront or was updated in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • _authentication    object

    Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.

  • company    string

    The name of the company for which the customer works.

    Example: BigCommerce

  • first_name    string
    required

    First name of the customer.

    Example: Jane

  • last_name    string
    required

    Last name of the customer.

    Example: Doe

  • email    string
    required

    Email address of the customer.

    Example: janedoe@example.com

  • phone    string

    Phone number of the customer.

    Example: 1234567890

  • store_credit    string

    The amount of credit the customer has. (Float, Float as String, Integer)

    Example: 0

  • registration_ip_address    string

    The customer’s IP address when they signed up.

    Example: 12.345.678.910

  • customer_group_id    integer

    The group to which the customer belongs.

    Example: 2

  • notes    string

    Store-owner notes on the customer.

  • tax_exempt_category    string

    If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.

  • accepts_marketing    boolean
    read-only

    Describes whether the customer accepts product review emails or abandon cart emails. Read-Only.

    Example: true

  • addresses    object

  • form_fields    array[object] or null
    read-only

    Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • reset_pass_on_login    boolean

    Force a password change on next login.

example

Create a New Customer

POST /customers
⚠️
This endpoint is deprecated.

Request

Creates a Customer. Required Fields

  • first_name
  • last_name
  • email Read Only Fields
  • id
  • date_created
  • date_modified
  • accepts_marketing
  • addresses
  • form_fields

Notes

The _authentication object exposes functionality associated with the customer’s ability to log in to the store. All properties of the _authentication object are optional. When the _authentication object is not supplied with an update request, then the existing customer password remains the same.

Updating Passwords

To manually update a customer password in the same way as the control panel, supply a value for the password field:

{
    "_authentication": {
        "password": "12w69Y217PYR96J"
    }
}

Confirming Passwords

An additional optional password_confirmation field can also be sent, providing password confirmation as a service:

{
    "_authentication": {
       "password": "12w69Y217PYR96J",
       "password_confirmation": "12w69Y217PYR96J"
    }
}

Forcing Password Resets

To force a customer to reset their password upon their next login attempt, give the force_reset field a value of true, as shown here:

{
    "_authentication": {
        "force_reset": true
    }
}

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

object | application/json

  • _authentication    object

    This can vary depending on the action being taken to update, validate or force a password change. See Customers V2, Update a customer (Deprecated).

  • company    string

  • first_name    string

  • last_name    string

  • phone    string

  • date_modified    string

  • store_credit    integer

  • registration_ip_address    string

  • customer_group_id    integer

  • notes    string

  • tax_exempt_category    string

example

Response

Body

application/json

  • id    integer
    read-only

    Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

    Example: 1

  • date_created    string
    read-only

    Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • date_modified    string
    read-only

    Date on which the customer updated their details in the storefront or was updated in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • _authentication    object

    Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.

  • company    string

    The name of the company for which the customer works.

    Example: BigCommerce

  • first_name    string
    required

    First name of the customer.

    Example: Jane

  • last_name    string
    required

    Last name of the customer.

    Example: Doe

  • email    string
    required

    Email address of the customer.

    Example: janedoe@example.com

  • phone    string

    Phone number of the customer.

    Example: 1234567890

  • store_credit    string

    The amount of credit the customer has. (Float, Float as String, Integer)

    Example: 0

  • registration_ip_address    string

    The customer’s IP address when they signed up.

    Example: 12.345.678.910

  • customer_group_id    integer

    The group to which the customer belongs.

    Example: 2

  • notes    string

    Store-owner notes on the customer.

  • tax_exempt_category    string

    If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.

  • accepts_marketing    boolean
    read-only

    Describes whether the customer accepts product review emails or abandon cart emails. Read-Only.

    Example: true

  • addresses    object

  • form_fields    array[object] or null
    read-only

    Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • reset_pass_on_login    boolean

    Force a password change on next login.

  • id    integer
    read-only

    Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

    Example: 1

  • date_created    string
    read-only

    Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • date_modified    string
    read-only

    Date on which the customer updated their details in the storefront or was updated in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • _authentication    object

    Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.

  • company    string

    The name of the company for which the customer works.

    Example: BigCommerce

  • first_name    string
    required

    First name of the customer.

    Example: Jane

  • last_name    string
    required

    Last name of the customer.

    Example: Doe

  • email    string
    required

    Email address of the customer.

    Example: janedoe@example.com

  • phone    string

    Phone number of the customer.

    Example: 1234567890

  • store_credit    string

    The amount of credit the customer has. (Float, Float as String, Integer)

    Example: 0

  • registration_ip_address    string

    The customer’s IP address when they signed up.

    Example: 12.345.678.910

  • customer_group_id    integer

    The group to which the customer belongs.

    Example: 2

  • notes    string

    Store-owner notes on the customer.

  • tax_exempt_category    string

    If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.

  • accepts_marketing    boolean
    read-only

    Describes whether the customer accepts product review emails or abandon cart emails. Read-Only.

    Example: true

  • addresses    object

  • form_fields    array[object] or null
    read-only

    Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • reset_pass_on_login    boolean

    Force a password change on next login.

example

Delete Customers

DELETE /customers
⚠️
This endpoint is deprecated.

Request

By default, it deletes all Customers. Up to 100 customers per batch can be deleted.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

example

Response

Get a Customer

GET /customers/{customer_id}
⚠️
This endpoint is deprecated.

Request

Returns a single Customer.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • customer_id in path - integer
    required

    Unique numeric ID of the customer.

example

Response

Body

application/json

  • id    integer
    read-only

    Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

    Example: 1

  • date_created    string
    read-only

    Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • date_modified    string
    read-only

    Date on which the customer updated their details in the storefront or was updated in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • _authentication    object

    Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.

  • company    string

    The name of the company for which the customer works.

    Example: BigCommerce

  • first_name    string
    required

    First name of the customer.

    Example: Jane

  • last_name    string
    required

    Last name of the customer.

    Example: Doe

  • email    string
    required

    Email address of the customer.

    Example: janedoe@example.com

  • phone    string

    Phone number of the customer.

    Example: 1234567890

  • store_credit    string

    The amount of credit the customer has. (Float, Float as String, Integer)

    Example: 0

  • registration_ip_address    string

    The customer’s IP address when they signed up.

    Example: 12.345.678.910

  • customer_group_id    integer

    The group to which the customer belongs.

    Example: 2

  • notes    string

    Store-owner notes on the customer.

  • tax_exempt_category    string

    If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.

  • accepts_marketing    boolean
    read-only

    Describes whether the customer accepts product review emails or abandon cart emails. Read-Only.

    Example: true

  • addresses    object

  • form_fields    array[object] or null
    read-only

    Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • reset_pass_on_login    boolean

    Force a password change on next login.

  • id    integer
    read-only

    Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

    Example: 1

  • date_created    string
    read-only

    Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • date_modified    string
    read-only

    Date on which the customer updated their details in the storefront or was updated in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • _authentication    object

    Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.

  • company    string

    The name of the company for which the customer works.

    Example: BigCommerce

  • first_name    string
    required

    First name of the customer.

    Example: Jane

  • last_name    string
    required

    Last name of the customer.

    Example: Doe

  • email    string
    required

    Email address of the customer.

    Example: janedoe@example.com

  • phone    string

    Phone number of the customer.

    Example: 1234567890

  • store_credit    string

    The amount of credit the customer has. (Float, Float as String, Integer)

    Example: 0

  • registration_ip_address    string

    The customer’s IP address when they signed up.

    Example: 12.345.678.910

  • customer_group_id    integer

    The group to which the customer belongs.

    Example: 2

  • notes    string

    Store-owner notes on the customer.

  • tax_exempt_category    string

    If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.

  • accepts_marketing    boolean
    read-only

    Describes whether the customer accepts product review emails or abandon cart emails. Read-Only.

    Example: true

  • addresses    object

  • form_fields    array[object] or null
    read-only

    Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • reset_pass_on_login    boolean

    Force a password change on next login.

example

Update a Customer

PUT /customers/{customer_id}
⚠️
This endpoint is deprecated.

Request

Updates a Customer.

Read Only Fields

  • id
  • date_created
  • date_modified
  • accepts_marketing
  • addresses
  • form_fields

Notes

The _authentication object exposes functionality associated with the customer’s ability to log in to the store. All properties of the _authentication object are optional. When the _authentication object is not supplied with an update request, then the existing customer password remains the same.

Updating Passwords

To manually update a customer password in the same way as the control panel, supply a value for the password field:

{
    "_authentication": {
        "password": "12w69Y217PYR96J"
    }
}

Confirming Passwords

An additional optional password_confirmation field can also be sent, providing password confirmation as a service:

{
    "_authentication": {
       "password": "12w69Y217PYR96J"
       "password_confirmation": "12w69Y217PYR96J"
    }
}

Forcing Password Resets

To force a customer to reset their password upon their next login attempt, give the force_reset field a value of true, as shown here:

{
    "_authentication": {
        "force_reset": true
    }
}

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

object | application/json

  • id    integer
    read-only

    Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

    Example: 1

  • _authentication    object

    Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.

  • company    string

    The name of the company for which the customer works.

    Example: BigCommerce

  • first_name    string

    First name of the customer.

    Example: Jane

  • last_name    string

    Last name of the customer.

    Example: Doe

  • email    string

    Email address of the customer.

    Example: janedoe@example.com

  • phone    string

    Phone number of the customer.

    Example: 1234567890

  • date_created    string
    read-only

    Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • date_modified    string
    read-only

    Date on which the customer updated their details in the storefront or was updated in the control panel. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

  • store_credit    string

    The amount of credit the customer has. (Float, Float as String, Integer)

    Example: 0

  • registration_ip_address    string

    The customer’s IP address when they signed up.

    Example: 12.345.678.910

  • customer_group_id    integer

    The group to which the customer belongs.

    Example: 2

  • notes    string

    Store-owner notes on the customer.

  • tax_exempt_category    string

    If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.

  • accepts_marketing    boolean
    read-only

    Describes whether the customer accepts product review emails and abandon cart emails. Read-Only.

    Example: true

  • addresses    object

  • form_fields    array[object]
    read-only

    Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • reset_pass_on_login    boolean

    Force a password change on next login.

example

Response

Body

object | application/json

  • _authentication    object

    Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.

  • company    string

    The name of the company for which the customer works.

    Example: BigCommerce

  • first_name    string
    required

    First name of the customer.

    Example: Jane

  • last_name    string
    required

    Last name of the customer.

    Example: Doe

  • email    string
    required

    Email address of the customer.

    Example: janedoe@example.com

  • phone    string

    Phone number of the customer.

    Example: 1234567890

  • store_credit    string

    The amount of credit the customer has. (Float, Float as String, Integer)

    Example: 0

  • registration_ip_address    string

    The customer’s IP address when they signed up.

    Example: 12.345.678.910

  • customer_group_id    integer

    The group to which the customer belongs.

    Example: 2

  • notes    string

    Store-owner notes on the customer.

  • tax_exempt_category    string

    If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.

  • accepts_marketing    boolean
    read-only

    Describes whether the customer accepts product review emails or abandon cart emails. Read-Only.

    Example: true

  • addresses    object

  • form_fields    array[object] or null
    read-only

    Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request.

  • reset_pass_on_login    boolean

    Force a password change on next login.

example

Delete a Customer

DELETE /customers/{customer_id}
⚠️
This endpoint is deprecated.

Request

Deletes a Customer.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • customer_id in path - integer
    required

    Unique numeric ID of the customer.

example

Response

Get a Count of Customers

GET /customers/count
⚠️
This endpoint is deprecated.

Request

Returns a count of all Customers.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

example

Response

Body

object | application/json

  • count    number

    Example: 27

example

Did you find what you were looking for?
Validate a customer credentialsGet All Customers