Partner Information
Becoming A Partner
Getting Started
POS Solutions
ERP Solutions
PIM Solutions
OMS Solutions
Marketing Solutions
Shipping Solutions
Payment Solutions
Provider APIs
Building Apps
Quick Start
Building Channels
Quick Start
Building Storefronts
Embedded Checkout
Managing Currencies

Customers and Subscribers

OAuth scopes

Name Permission Parameter
Customers modify store_v2_customers
Customers read-only store_v2_customers_read_only

For more information on available authentication methods, see Authentication.

What is a customer?

A customer is anyone who makes a purchase on a store and creates an account. BigCommerce stores an email address, customer address, and name against the customer as a record. There are two APIs you can use to manipulate customer data. You can extend the data for customer records using the custom account sign-up form fields and customer attributes endpoints (V3).

Customer groups

Customer groups allow you to organize your customers, give them discounts, and restrict access to specific products or categories. For more information see Customer Groups.

Customer groups by plan

Customer groups are only available on specific plans. See BigCommerce Pricing to learn more.

What is a subscriber?

A subscriber is someone who has signed up for a store’s newsletter. The location of the sign-up field is in the footer of most storefront themes.

Subscribers can also be added by:

  • Signing up for the newsletter during checkout
  • Sending a POST request to the Subscribers API

Where possible, the API indicates the origin of the subscriber. When customers sign up for the newsletter using One-Page Checkout, the Order ID becomes part of the subscriber’s record. When customers use Optimized One-Page Checkout, the customer becomes a subscriber before checking out, resulting in a subscriber record without an Order ID.

Subscribers vs. customers

  • A subscriber is not always a customer. Someone can sign up for the newsletter without creating 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 both a customer and a subscriber.

What is a guest?

Store settings can be configured to allow a shopper to complete checkout without creating an account. These shoppers are not captured as customers or stored on BigCommerce. If you want to capture guest data, using the Storefront APIs can help.

Customer Login API

The Customer Login API allows for single sign-on. Once a customer has authenticated by logging in to a third-party system (CMS, portal, or app), you can use the Customer Login API to seamlessly log the customer into their BigCommerce customer account.

Current Customer API

The Current Customer API allows your application to identify logged in customers. This identification is useful when you need to show customer-specific information.

Customers API

There are two Customers API endpoints available:

  • V3 Customers API
  • V2 Customers API

V3 Customers API

The V3 Customers API is comprised of customers, customer attributes, customer address, and customer form fields.

A customer makes a purchase on a store and creates an account. The customers object comprises a customer’s address, attributes, form fields and authentication. The V3 Customers API can accomplish the same tasks as the existing V2 Customers API, with greater efficiency.

Customer Attributes and Customer Attribute Values let you store additional information against a customer. Customer Attributes define a the name of a key/value pair and the type of information stored (for example, "name": "Shoe size", "type": "number"). The Customer Attribute Values endpoint lets you define the values for the attributes.

Name value pairs

Each customer can have up to 50 name, value pairs stored.

Customer attributes are created separately from the customer. After the name and type are created, then the attributes can be added to the customer using the name, value pair.

Customer addresses consist of a customers address and phone number. Customers can have multiple addresses stored against them.

Customer form field values are fields on either the customer address or customer signup that accept any string data. An example of a signup field can have a customer input a wholesaler ID or, for an address field, have them input any special delivery instructions. For more information about creating form fields, see Account Signup Fields.

You can access and edit the values for the fields on customer and customer address records using the API.

V2 Customers API

The V2 Customers API is comprised of customers, customer addresses and customer groups. The customers object is comprised of basic customer information such as customer name and phone number.

Customer addresses consist of a customer’s address and phone number. Customers can have multiple addresses stored against them.

Customer groups allow you to organize your customers, give them discounts, and restrict access to specific products or categories. Customer groups are not yet available on the V3 Customers API.

Differences between V2 and V3 Customer API

Making requests

The V3 Customers API is easier to use. It reduces the API calls needed to accomplish a task. For example, when creating a new customer with the V2 API, there was a need to make calls to several endpoints. Now customer attributes and address are created in one step, allowing you to batch create multiple customers — and their subresources — in a single API call.

Create a customer

Single customer on V3

  • /customers

Single customer on V2

  • /customers/{customer_id}
  • /customers/{customer_id}/addresses


With the V3 Customers API, queries become a powerful tool. There is one GET endpoint per resource with filters to refine the request. The V2 API necessitates using a different endpoint to get customer subresources.

Get customer addresses

Get customer address by name and company on V3:


Get customer address by name and company on V2:



POST and PUT requests on this endpoint require an array object.

Example Update a Customer (V3)


    "id": 12,
    "email": "",
    "first_name": "Jane",
    "last_name": "Doe"

Example Update a Customer (V2)


  "first_name": "Jane",
  "email": "",
  "phone": "1234567890"


Upsert is used for form field values and customer attributes. Upsert looks for a match to the existing record, and if one is found, then it makes an update. If a match is not found, it creates a new record.

Authentication object

When creating a customer there are two ways to set customers passwords on the V3 customers endpoint.

  • A new password can be set under the authentication > new password object in a /PUT or /POST.
  • To have customers reset the password set force_password_reset to true under authentication > new password object in a PUT or POST request

Password confirmation and validation are still available under V2 customers.

Subscribers API

The Subscribers API allows you to manage subscribers who have signed up for the store’s newsletter.


Which API should I use?

Use the V3 Customers API when possible as we will eventually begin the process of deprecating the existing V2 Customers API.

How can I validate customer passwords?

Password validation is only available on V2 Customers API. Validation will return a boolean. The V3 Customers API can reset a customer’s password or input a new password.

Related resources