Customers and Subscribers




The following OAuth scopes are required:

  • Customers View/Modify
  • Customers Login

What is a Customer?

A customer is anyone who has made a purchase on a store and created an account. BigCommerce then stores email address, customer address, and name against the customer as a record. You can also extend the data for your customer records using custom account sign up form fields and the customer attributes API.

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.

What is a Subscriber?

A subscriber is someone who has signed up for a store’s newsletter.
Subscribers can be added by:

  • Signing up for the newsletter via the signup box located in the footer of most storefront themes
  • Signing up for the newsletter during checkout
  • POSTing to the Subscribers API

Where possible, the API indicates the origin of the subscriber. If the subscriber was added during checkout, the Order ID is included.

Subscribers vs. Customers

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

What is a Guest?

Store settings can be set to allow a shopper to complete checkout without creating an account. These shoppers are not captured as customers or stored in the BigCommerce system. 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 is useful when you need to show customer specific information.

Customer API

There are two Customer 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.

Customers are any shopper that has created an account on the store. The Customers object comprises customers 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 are a name, value key pair that are stored against a Customer. For example, if you want to keep a list of hat sizes, the name can be “Hat Sizes” and the value can be 10. Each customer can have several name, value pairs stored.

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 Fields 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. Creating form fields needs to be done from the Control Panel. Using the API you are able to access and edit the values for the fields on your Customer and Customer Address records.

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 customers 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 new Customers API is easier to use. It reduces the API calls needed to accomplish a task. For example, creating a new Customer with the V2 API there was a need to hit several endpoints. Now the customer attributes and address are created in one step with Create a Customer, 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. Instead of using a different endpoint to get customer sub-resources, there is one GET endpoint per resource with filters to refine the request.

Get Customer Addresses

Get Customer Address by name and company on V3 /customers/addresses?company:in=bigcommerce,commongood&customer_id:in1,2,3

Get Customer Address by name and company on V2 /customers/{customer_id}/addresses/{customer_address_id}


Requests on this endpoint require an array object for all Create and Update Actions.

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

On the new Customers endpoint, when creating a customer there are two ways to set customers passwords.

  • 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

Password Confirmation and Validation are still available under V2 Customers.


Which API should I use?

When possible use the V3 Customers API since 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 true or false. The V3 Customers API can reset a customers password or input a new password.


Related Endpoints

Customer Login API


Related Articles