BigCommerce API Customers

This guide covers the BigCommerce API for managing customers, including creating, updating, retrieving, and deleting customer records. It provides detailed information on the required fields, optional parameters, and filtering options available for customer-related operations.

What can you do with Customers in the BigCommerce API?

The most common operations people perform on customers using the BigCommerce API.

Action	HTTP Method	Endpoint
List All Customers	`GET`	`/customers`
Create Customers	`POST`	`/customers`
Update Customers	`PUT`	`/customers`
Delete Customers	`DELETE`	`/customers`

Customers represent individuals or entities that interact with your store. They can be created, updated, retrieved, and deleted using the BigCommerce API.

Customers are identified by a unique numeric ID. This ID is used in various endpoints to perform operations on specific customer records.

To create a customer, you must provide the first_name, last_name, and email fields. Additional fields such as company, phone, and addresses are optional.

Customers can be searched using various query parameters such as id:in, email:in, name:like, and date_created. For example, to filter customers by email, use email:in=janedoe@example.com.

Properties of a Customer

This section describes the properties of a customer object, including essential and additional fields. Show all properties Only show essential properties

Field Name	Type	Short Description
id	integer	The unique numeric ID of the customer.
email	string	The email of the customer. Must be unique.
first_name	string	The first name of the customer.
last_name	string	The last name of the customer.
company	string	The company of the customer.
phone	string	The phone number of the customer.
registration_ip_address	string	The IP address from which this customer was registered.
customer_group_id	integer	ID of the group which this customer belongs to.
date_created	datetime	The date of which the customer was created.
date_modified	datetime	The date on which the customer was modified.
notes	string	The customer notes.
tax_exempt_category	string	The tax exempt category code for the customer.
address_count	integer	Total number of customer addresses.
attribute_count	integer	Total number of customer attributes.
authentication	object	Customer authentication details.
addresses	array	Array of customer addresses. Limited to 10.
attributes	array	Array of customer attributes. Limited to 10.
form_fields	array	Array of form fields. Controlled by <code>formfields</code> parameter.
store_credit_amounts	array	Store credit amounts associated with the customer.
accepts_product_review_abandoned_cart_emails	boolean	Determines if the customer is signed up to receive product review or abandoned cart emails.
origin_channel_id	integer	Channel ID of the customer that has created the form.
channel_ids	array	Array of channels the customer can access.

Show all properties

Filtering and Query Parameters

The API provides several filtering and query options to narrow down the list of customers returned by the GET endpoint.

Parameter	Type	Description	Example
`page`	integer	Page number for pagination.	`page=1`
`limit`	integer	Number of items per page.	`limit=50`
`id:in`	array	Filter by customer IDs.	`id:in=4,5,6`
`company:in`	array	Filter by company names.	`company:in=bigcommerce,commongood`
`customer_group_id:in`	array	Filter by customer group IDs.	`customer_group_id:in=5,6`
`date_created`	datetime	Filter by creation date.	`date_created=2018-09-05T13:43:54`
`date_created:max`	string	Filter by maximum creation date.	`date_created:max=2018-09-10`
`date_created:min`	datetime	Filter by minimum creation date.	`date_created:min=2018-09-05`
`date_modified`	datetime	Filter by modification date.	`date_modified=2018-09-05T13:45:03`
`date_modified:min`	string	Filter by minimum modification date.	`date_modified:min=2019-09-04T:00:00:00`
`date_modified:max`	datetime	Filter by maximum modification date.	`date_modified:max=2018-09-05T13:45:03`
`email:in`	string	Filter by email addresses.	`email:in=janedoe@example.com`
`name:in`	array	Filter by full name.	`name:in=James Moriarty`
`name:like`	array	Filter by substring in name.	`name:like=moriarty, sherlock`
`registration_ip_address:in`	array	Filter by registration IP address.	`registration_ip_address:in=12.345.6.789`
`include`	array	Include customer sub-resources.	`include=addresses,storecredit,attributes,formfields,shopper_profile_id,segment_ids`
`sort`	string	Sort by specified fields.	`sort=last_name:asc`

What to watch out for

Be aware of these common pitfalls and important considerations when working with the Customers API.

Unique Email Requirement

The email field must be unique for each customer. Attempting to create or update a customer with a duplicate email will result in an error.

Immutable Fields

Certain fields such as id, registration_ip_address, date_created, and date_modified are read-only and cannot be modified.

Rate Limiting

The API has rate limits in place. Ensure your application handles rate limit responses appropriately to avoid disruptions.

Channel-Specific Access

When creating a customer, you can specify channel_ids for channel-specific access. Ensure the channel has allow_global_logins enabled if you omit channel_ids.

Attribute Updates

Customer attribute values cannot be updated using the Update Customer endpoint. Use the appropriate endpoint for updating attribute values.

Frequently Asked Questions

Here are some frequently asked questions about the Customers API.

How do I find a customer by email?

Use the email:in query parameter with the GET /customers endpoint. For example, email:in=janedoe@example.com.

What happens when I update a customer?

When updating a customer, ensure that you include the id field in the request body. Only modifiable fields will be updated.

Can I delete a customer without specifying an ID?

No, you must specify the id:in query parameter with the DELETE /customers endpoint to delete a customer.

How do I filter customers by creation date?

Use the date_created, date_created:min, or date_created:max query parameters with the GET /customers endpoint.

What are the required fields for creating a customer?

The required fields for creating a customer are first_name, last_name, and email.

How do I handle rate limits?

Implement retry logic in your application to handle rate limit responses. Check the response headers for rate limit information.