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

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: {{token}}'

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
  • 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.

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"
},
"reset_pass_on_login": false
}
]

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: json { "_authentication": { "password": "12w69Y217PYR96J" } } ## Confirming Passwords An additional optional password_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 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 - string
    required
    The MIME type of the response body.
  • 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

{
"_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

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
  • 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
  • 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.

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"
},
"reset_pass_on_login": false
}

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

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: {{token}}'

Response

Get a Customer

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

Request

Returns a single Customer.

Authentication

  • X-Auth-Token in header

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: {{token}}'

Response

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
  • 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
  • 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.

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"
},
"reset_pass_on_login": false
}

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: 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 - string
    required
    The MIME type of the response body.
  • customer_id in path - integer
    required
    Unique numeric ID of the customer.
  • 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
  • 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.

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"
},
"reset_pass_on_login": false
}

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
  • 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.

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"
},
"reset_pass_on_login": false
}

Delete a Customer

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

Request

Deletes a Customer.

Authentication

  • X-Auth-Token in header

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: {{token}}'

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

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: {{token}}'

Response

Body

object | application/json
  • count
    number

    Example: 27

example

{
"count": 27
}

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?