Customers V2

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

Available Endpoints

Resource / Endpoint	Description
Customers	Identity and account details for customers shopping on BigCommerce stores
Customers Addresses	Postal address belonging to a customer.
Customers Groups	Groupings of customers who share the same level of access and discounts
Customers Validate Password	Validate 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

Customer Login API

Webhooks

Customers

Get All Customers

GET https://api.bigcommerce.com/stores/{store_hash}/v2/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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/customers' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

array | application/json

example

[
  {
    "id": 1,
    "date_created": "string",
    "date_modified": "string",
    "_authentication": {
      "force_reset": true,
      "password": "string",
      "password_confirmation": "string"
    },
    "company": "BigCommerce",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "janedoe@example.com",
    "phone": "1234567890",
    "store_credit": "0",
    "registration_ip_address": "12.345.678.910",
    "customer_group_id": 2,
    "notes": "string",
    "tax_exempt_category": "string",
    "addresses": {
      "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/customers/5/addresses",
      "resource": "/customers/5/addresses"
    },
    "form_fields": [
      {
        "name": "License Id",
        "value": "string"
      }
    ],
    "reset_pass_on_login": false
  }
]

Create a New Customer

POST https://api.bigcommerce.com/stores/{store_hash}/v2/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

_authenticationobject
This can vary depending on the action being taken to update, validate or force a password change. See Update Customer
companystring
first_namestring
last_namestring
phonestring
date_modifiedstring
store_creditinteger
registration_ip_addressstring
customer_group_idinteger
notesstring
tax_exempt_categorystring

example

{
  "_authentication": {},
  "company": "string",
  "first_name": "string",
  "last_name": "string",
  "phone": "string",
  "date_modified": "string",
  "store_credit": 0,
  "registration_ip_address": "string",
  "customer_group_id": 0,
  "notes": "string",
  "tax_exempt_category": "string"
}

Response

Body

application/json

idinteger
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_createdstring
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_modifiedstring
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.

_authenticationobject
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.
companystring
The name of the company for which the customer works.
Example: BigCommerce
first_namestring
required
First name of the customer.
Example: Jane
last_namestring
required
Last name of the customer.
Example: Doe
emailstring
required
Email address of the customer.
Example: janedoe@example.com
phonestring
Phone number of the customer.
Example: 1234567890
store_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)
Example: 0
registration_ip_addressstring
The customer’s IP address when they signed up.
Example: 12.345.678.910
customer_group_idinteger
The group to which the customer belongs.
Example: 2
notesstring
Store-owner notes on the customer.
tax_exempt_categorystring
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_marketingboolean
If the customer accepts product review emails or abandon cart emails. Read-Only.
Example: true
addressesobject
form_fieldsarray[object]
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_loginboolean
Force a password change on next login.
Example: false

example

{
  "id": 1,
  "date_created": "string",
  "date_modified": "string",
  "_authentication": {
    "force_reset": true,
    "password": "string",
    "password_confirmation": "string"
  },
  "company": "BigCommerce",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "janedoe@example.com",
  "phone": "1234567890",
  "store_credit": "0",
  "registration_ip_address": "12.345.678.910",
  "customer_group_id": 2,
  "notes": "string",
  "tax_exempt_category": "string",
  "addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/customers/5/addresses",
    "resource": "/customers/5/addresses"
  },
  "form_fields": [
    {
      "name": "License Id",
      "value": "string"
    }
  ],
  "reset_pass_on_login": false
}

Delete Customers

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/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

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/customers' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Get a Customer

GET https://api.bigcommerce.com/stores/{store_hash}/v2/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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/customers/[customer_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

application/json

idinteger
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_createdstring
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_modifiedstring
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.

_authenticationobject
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.
companystring
The name of the company for which the customer works.
Example: BigCommerce
first_namestring
required
First name of the customer.
Example: Jane
last_namestring
required
Last name of the customer.
Example: Doe
emailstring
required
Email address of the customer.
Example: janedoe@example.com
phonestring
Phone number of the customer.
Example: 1234567890
store_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)
Example: 0
registration_ip_addressstring
The customer’s IP address when they signed up.
Example: 12.345.678.910
customer_group_idinteger
The group to which the customer belongs.
Example: 2
notesstring
Store-owner notes on the customer.
tax_exempt_categorystring
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_marketingboolean
If the customer accepts product review emails or abandon cart emails. Read-Only.
Example: true
addressesobject
form_fieldsarray[object]
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_loginboolean
Force a password change on next login.
Example: false

example

{
  "id": 1,
  "date_created": "string",
  "date_modified": "string",
  "_authentication": {
    "force_reset": true,
    "password": "string",
    "password_confirmation": "string"
  },
  "company": "BigCommerce",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "janedoe@example.com",
  "phone": "1234567890",
  "store_credit": "0",
  "registration_ip_address": "12.345.678.910",
  "customer_group_id": 2,
  "notes": "string",
  "tax_exempt_category": "string",
  "addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/customers/5/addresses",
    "resource": "/customers/5/addresses"
  },
  "form_fields": [
    {
      "name": "License Id",
      "value": "string"
    }
  ],
  "reset_pass_on_login": false
}

Update a Customer

PUT https://api.bigcommerce.com/stores/{store_hash}/v2/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

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

idinteger
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
_authenticationobject
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.
companystring
The name of the company for which the customer works.
Example: BigCommerce
first_namestring
required
First name of the customer.
Example: Jane
last_namestring
required
Last name of the customer.
Example: Doe
emailstring
required
Email address of the customer.
Example: janedoe@example.com
phonestring
Phone number of the customer.
Example: 1234567890
date_createdstring
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_modifiedstring
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_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)
Example: 0
registration_ip_addressstring
The customer’s IP address when they signed up.
Example: 12.345.678.910
customer_group_idinteger
The group to which the customer belongs.
Example: 2
notesstring
Store-owner notes on the customer.
tax_exempt_categorystring
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_marketingboolean
If the customer accepts product review emails or abandon cart emails. Read-Only.
Example: true
addressesobject
form_fieldsarray[object]
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_loginboolean
Force a password change on next login.
Example: false

example

{
  "id": 1,
  "_authentication": {
    "force_reset": true,
    "password": "string",
    "password_confirmation": "string"
  },
  "company": "BigCommerce",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "janedoe@example.com",
  "phone": "1234567890",
  "date_created": "string",
  "date_modified": "string",
  "store_credit": "0",
  "registration_ip_address": "12.345.678.910",
  "customer_group_id": 2,
  "notes": "string",
  "tax_exempt_category": "string",
  "addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/customers/5/addresses",
    "resource": "/customers/5/addresses"
  },
  "form_fields": [
    {
      "name": "License Id",
      "value": "123BAF"
    }
  ],
  "reset_pass_on_login": false
}

Response

Body

object | application/json

_authenticationobject
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.
companystring
The name of the company for which the customer works.
Example: BigCommerce
first_namestring
required
First name of the customer.
Example: Jane
last_namestring
required
Last name of the customer.
Example: Doe
emailstring
required
Email address of the customer.
Example: janedoe@example.com
phonestring
Phone number of the customer.
Example: 1234567890
store_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)
Example: 0
registration_ip_addressstring
The customer’s IP address when they signed up.
Example: 12.345.678.910
customer_group_idinteger
The group to which the customer belongs.
Example: 2
notesstring
Store-owner notes on the customer.
tax_exempt_categorystring
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_marketingboolean
If the customer accepts product review emails or abandon cart emails. Read-Only.
Example: true
addressesobject
form_fieldsarray[object]
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_loginboolean
Force a password change on next login.
Example: false

example

{
  "_authentication": {
    "force_reset": true,
    "password": "string",
    "password_confirmation": "string"
  },
  "company": "BigCommerce",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "janedoe@example.com",
  "phone": "1234567890",
  "store_credit": "0",
  "registration_ip_address": "12.345.678.910",
  "customer_group_id": 2,
  "notes": "string",
  "tax_exempt_category": "string",
  "addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/customers/5/addresses",
    "resource": "/customers/5/addresses"
  },
  "form_fields": [
    {
      "name": "License Id",
      "value": "string"
    }
  ],
  "reset_pass_on_login": false
}

Delete a Customer

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/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

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/customers/[customer_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Get a Count of Customers

GET https://api.bigcommerce.com/stores/{store_hash}/v2/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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/customers/count' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

countnumber
Example: 27

example

{
  "count": 27
}

Customers V2

Available Endpoints

Usage Notes

Resources

Related APIs / Endpoints

Webhooks

Get All Customers

Request

Authentication

Parameters

example

Response

Body

example

Create a New Customer

Request

Notes

Updating Passwords

Confirming Passwords

Forcing Password Resets

Authentication

Parameters

Body

_authenticationobject

companystring

first_namestring

last_namestring

phonestring

date_modifiedstring

store_creditinteger

registration_ip_addressstring

customer_group_idinteger

notesstring

tax_exempt_categorystring

example

Response

Body

idinteger

date_createdstring

date_modifiedstring

_authenticationobject

companystring

first_namestringrequired

last_namestringrequired

emailstringrequired

phonestring

store_creditstring

registration_ip_addressstring

customer_group_idinteger

notesstring

tax_exempt_categorystring

accepts_marketingboolean

addressesobject

form_fieldsarray[object]

reset_pass_on_loginboolean

example

Delete Customers

Request

Authentication

Parameters

example

Response

Get a Customer

Request

Authentication

Parameters

example

Response

Body

idinteger

date_createdstring

date_modifiedstring

_authenticationobject

companystring

first_namestringrequired

last_namestringrequired

emailstringrequired

phonestring

store_creditstring

registration_ip_addressstring

first_namestring
required

last_namestring
required

emailstring
required

first_namestring
required

last_namestring
required

emailstring
required

first_namestring
required

last_namestring
required

emailstring
required

first_namestring
required

last_namestring
required

emailstring
required