BigCommerce
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

    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

      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

      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

      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

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

      Example: true

    • addresses
      object

    • form_fields
      array[object] or null

      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: false

      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

        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

        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

        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

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

        Example: true

      • addresses
        object

      • form_fields
        array[object] or null

        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: false

        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

          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

          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

          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

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

          Example: true

        • addresses
          object

        • form_fields
          array[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_login
          boolean

          Force a password change on next login.

          Example: false

        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

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

          Example: true

        • addresses
          object

        • form_fields
          array[object] or null

          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: false

        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?