Customers and Subscribers
The following overview covers the authentication patterns and API endpoints that BigCommerce offers for customer management.
For more information on available authentication methods, see Authentication.
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 allow you to organize your customers, give them discounts, and restrict access to specific products or categories. For more information, see Customer Groups (opens in a new tab).
Customer groups are only available on specific plans. See BigCommerce Pricing (opens in a new tab) to learn more.
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
POSTrequest 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.
- 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.
Store settings (opens in a new tab) 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.
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.
The Current Customer API allows your application to identify logged-in customers. This identification is useful when you need to show customer-specific information.
There are two Customers API endpoints available:
- V3 Customers API
- V2 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 the name of a name-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.
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 sign-up that accept any string data. For example, a sign-up 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 (opens in a new tab).
You can access and edit the values for the fields on customer and customer address records using the 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.
When resources are available through both APIs, we recommend using the V3 Customers API as BigCommerce will eventually migrate all existing V2 resources to V3.
This section covers the important differences between V2 and V3 Customers APIs.
The V3 Customers API is easier to use. It reduces the number of API calls needed to accomplish a task. For example, to create a new customer with the V2 API, you have to make multiple API calls. With the V3 API, you can create customer attributes and address 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:
Single customer on V2:
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:
PUT requests require an array object.
You can use the V3 Customers API Upsert Customer Attribute Values operation to upsert form field values and customer attributes. Upsert looks for a match to the existing record and makes an update if there is one. If there is no match, it creates a new record.
The V3 Customers API offers two ways to set a customer's password:
- You can set a new password under the
authentication > new_passwordobject in a
- To prompt a customer to reset their password, set
authentication > new_passwordobject in a
The Subscribers API allows you to manage subscribers who have signed up for the store’s newsletter.
Which API should I use?
When possible, use the V3 Customers API as BigCommerce will eventually deprecate the existing V2 Customers API.
How can I validate customer passwords?
Password validation is only available on the V2 Customers API at this time. We recommend using the V3 Customers API to reset or input a new password as BigCommerce intends to deprecate the V2 Customers API.
- Adding and Editing Fields in the Account Signup Form (Help Center) (opens in a new tab)
- Checkout Settings (Help Center) (opens in a new tab)
- Customer Login API
- Current Customer API
- Customers V3 API
- Customer Groups (Customers V2 API)
- Password Validation (Customers V2 API)
- Password Confirmation (Customers V2 API)
- Storefront Subscriptions
- Subscribers API