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 purchases from a store and creates an account. BigCommerce stores an email address, customer address, and name in the customer object.

You can extend the data for customer records using customer metafields, custom account sign-up form fields, and customer attributes endpoints.

You can use the following APIs to work with customer data and authentication:

• GraphQL Storefront API
• REST storefront customers API
• REST management API V3 customers
• REST management API V2 customers
• Customer login API
• Current customer API

Customer groups

Customer groups let you organize customers, give them discounts, and restrict access to specific products or categories. For more information, see Customer Groups (Help Center) (opens in a new tab).

What is a subscriber?

A subscriber is someone who signs up for a store's newsletter or abandoned cart emails. The sign-up field is located in the footer of most storefront themes.

You can also add subscribers in the following ways:

• Exposing a newsletter sign-up field during checkout

• Sending a request to the Create a subscriber endpoint in the REST Management 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 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

The following endpoints are available:

GraphQL API

• Customers GraphQL API

REST API

• V3 customers REST API
• V2 customers REST API

V3 customers API

The V3 customers API consists of customers, customer address books, customer attributes, customer addresses, customer form fields, and other endpoints that help manage the customer object.

A customer can purchase from a store and create an account. The customers object comprises both customer details and a customer address book.

Customer details include data preferences, attribute fields, form fields, and authentication. The V3 customers API can accomplish the same tasks as the existing V2 customers API, with greater efficiency.

The customer address book stores a collection of addresses entered by the customer. Add an address to capture the customer address details where you can ship orders if selected.

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 sign up 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 consists of customers, customer addresses, and customer groups. The customer's object consists 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 let you 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 their 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 or have signed up for abandoned cart emails. An important field to note is consents - this field determines whether the Subscriber signed up for marketing newsletter emails, abandoned cart emails, or both. This field can also be empty, meaning they have not subscribed to either (or may have opted out).

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/customers/subscribers
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "email": "string@test.com",
  "first_name": "string",
  "last_name": "string",
  "channel_id": 1,
  "consents": ["marketing_newsletter", "abandoned_cart"],
  "source": "storefront"
}

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/customers/subscribers/1
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "email": "string@test.com",
  "first_name": "string",
  "last_name": "string",
  "channel_id": 1,
  "consents": [],
  "source": "order"
}

Related resources

Articles

• Adding and Editing Fields in the Account sign up Form (Help Center) (opens in a new tab)
• Checkout Settings (Help Center) (opens in a new tab)

API

• Customer Login API
• Current Customer API

REST storefront API

• Customers
• Cookie consents
• Subscriptions

REST management API V3

• Customers
• Subscribers
• Validate customer credentials
• Customer segmentation

REST management API V2

• Customer groups

Webhooks

• Customers