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 / 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
Webhooks
Get All Customers
GET https://api.bigcommerce.com/stores/{store_hash}/v2/customersRequest
customer_ID
, from lowest to highest. Optional parameters can be passed in.Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe 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
idinteger
read-onlyUnique 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: 1date_createdstring
read-onlyDate 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
read-onlyDate 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: BigCommercefirst_namestring
requiredFirst name of the customer.Example: Janelast_namestring
requiredLast name of the customer.Example: Doeemailstring
requiredEmail address of the customer.Example: janedoe@example.comphonestring
Phone number of the customer.Example: 1234567890store_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)Example: 0registration_ip_addressstring
The customer’s IP address when they signed up.Example: 12.345.678.910customer_group_idinteger
The group to which the customer belongs.Example: 2notesstring
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
read-onlyDescribes whether the customer accepts product review emails or abandon cart emails. Read-Only.Example: trueaddressesobject
form_fieldsarray[object] or null
read-onlyArray 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
Create a New Customer
POST https://api.bigcommerce.com/stores/{store_hash}/v2/customersRequest
Creates a Customer. Required Fields
first_name
last_name
email
Read Only Fieldsid
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:json { "_authentication": { "password": "12w69Y217PYR96J" } }
## Confirming Passwords An additional optionalpassword_confirmation
field can also be sent, providing password confirmation as a service:json { "_authentication": { "password": "12w69Y217PYR96J", "password_confirmation": "12w69Y217PYR96J" } }
## Forcing Password Resets To force a customer to reset their password upon their next login attempt, give theforce_reset
field a value of true, as shown here:js showLineNumbers copy { "_authentication": { "force_reset": true } }
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
Body
_authenticationobject
This can vary depending on the action being taken to update, validate or force a password change. See Customers V2, Update a customer (Deprecated).companystring
first_namestring
last_namestring
phonestring
date_modifiedstring
store_creditinteger
registration_ip_addressstring
customer_group_idinteger
notesstring
tax_exempt_categorystring
example
Response
Body
idinteger
read-onlyUnique 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: 1date_createdstring
read-onlyDate 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
read-onlyDate 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: BigCommercefirst_namestring
requiredFirst name of the customer.Example: Janelast_namestring
requiredLast name of the customer.Example: Doeemailstring
requiredEmail address of the customer.Example: janedoe@example.comphonestring
Phone number of the customer.Example: 1234567890store_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)Example: 0registration_ip_addressstring
The customer’s IP address when they signed up.Example: 12.345.678.910customer_group_idinteger
The group to which the customer belongs.Example: 2notesstring
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
read-onlyDescribes whether the customer accepts product review emails or abandon cart emails. Read-Only.Example: trueaddressesobject
form_fieldsarray[object] or null
read-onlyArray 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
Delete Customers
DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/customersRequest
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
example
Response
Get a Customer
GET https://api.bigcommerce.com/stores/{store_hash}/v2/customers/{customer_id}Request
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- customer_id in path - integerrequiredUnique numeric ID of the customer.
example
Response
Body
idinteger
read-onlyUnique 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: 1date_createdstring
read-onlyDate 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
read-onlyDate 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: BigCommercefirst_namestring
requiredFirst name of the customer.Example: Janelast_namestring
requiredLast name of the customer.Example: Doeemailstring
requiredEmail address of the customer.Example: janedoe@example.comphonestring
Phone number of the customer.Example: 1234567890store_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)Example: 0registration_ip_addressstring
The customer’s IP address when they signed up.Example: 12.345.678.910customer_group_idinteger
The group to which the customer belongs.Example: 2notesstring
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
read-onlyDescribes whether the customer accepts product review emails or abandon cart emails. Read-Only.Example: trueaddressesobject
form_fieldsarray[object] or null
read-onlyArray 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
Update a Customer
PUT https://api.bigcommerce.com/stores/{store_hash}/v2/customers/{customer_id}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:
js showLineNumbers copy
{
"_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:
js showLineNumbers copy
{
"_authentication": {
"force_reset": true
}
}
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- customer_id in path - integerrequiredUnique numeric ID of the customer.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
Body
idinteger
read-onlyUnique 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: BigCommercefirst_namestring
First name of the customer.Example: Janelast_namestring
Last name of the customer.Example: Doeemailstring
Email address of the customer.Example: janedoe@example.comphonestring
Phone number of the customer.Example: 1234567890date_createdstring
read-onlyDate 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
read-onlyDate 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: 0registration_ip_addressstring
The customer’s IP address when they signed up.Example: 12.345.678.910customer_group_idinteger
The group to which the customer belongs.Example: 2notesstring
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
read-onlyDescribes whether the customer accepts product review emails and abandon cart emails. Read-Only.Example: trueaddressesobject
form_fieldsarray[object]
read-onlyArray 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
Response
Body
_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: BigCommercefirst_namestring
requiredFirst name of the customer.Example: Janelast_namestring
requiredLast name of the customer.Example: Doeemailstring
requiredEmail address of the customer.Example: janedoe@example.comphonestring
Phone number of the customer.Example: 1234567890store_creditstring
The amount of credit the customer has. (Float, Float as String, Integer)Example: 0registration_ip_addressstring
The customer’s IP address when they signed up.Example: 12.345.678.910customer_group_idinteger
The group to which the customer belongs.Example: 2notesstring
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
read-onlyDescribes whether the customer accepts product review emails or abandon cart emails. Read-Only.Example: trueaddressesobject
form_fieldsarray[object] or null
read-onlyArray 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
Delete a Customer
DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/customers/{customer_id}Request
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- customer_id in path - integerrequiredUnique numeric ID of the customer.
example
Response
Get a Count of Customers
GET https://api.bigcommerce.com/stores/{store_hash}/v2/customers/countRequest
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
example
Response
Body
countnumber
Example: 27
example
See something you can improve? Edit this file on GitHub