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

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]

      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]

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

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

          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

        Validate a customer credentialsGet All Customers