Customers and Subscribers

The following overview covers the authentication patterns and API endpoints that BigCommerce offers for customer management.

OAuth scopes

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 (opens in a new tab).

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

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

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

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.

Making requests

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:

-/customers

Single customer on V2:

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

Queries

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:

/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

V3 Customers POST and PUT requests require an array object.

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/customers
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "id": 12,
    "email": "janedoe@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }
]

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v2/customer_groups/{{customer_group_id}}
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "first_name": "Jane",
  "email": "jane@example.com",
  "phone": "1234567890"
}

Upsert

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.

Authentication object

The V3 Customers API offers two ways to set a customer's password:

• You can set a new password under the authentication > new_password object in a PUT or POST request.
• To prompt a customer to reset their 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 the V2 Customers API.

Subscribers API

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

FAQ

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.

Related resources

Articles

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

Endpoints

• 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

Webhooks

• Customer