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

    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

    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

    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

    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

    example

    Response

    Body

    application/json

    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

    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

    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

    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

    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

    example

    Response

    Body

    object | application/json
    • count
      number

      Example: 27

    example

    Did you find what you were looking for?