Docs
Management API
Customers V3

Customers V3

Create and manage customers.

Resources

Get All Customers

GET /customers

Request

Returns a list of Customers. Optional filter parameters can be passed in.

Notes

Attribute names are not available on the customer object.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • page in query - integer
    Page number (page will be ignored if you provide before or after in the request). For example page=1.
  • limit in query - number
    Items count per page. limit=50
  • id:in in query - array

    Filter items by ID. id:in=4,5,6

    Type: array[integer]
  • company:in in query - array
    Filter items by company. company:in=bigcommerce,commongood
    Type: array[string]
  • customer_group_id:in in query - array
    Filter items by customer_group_id. customer_group_id:in=5,6
    Type: array[string]
  • date_created in query - string
    Filter items by date created, for example, 2024-05-14T09:34:00 or 2024-05-14.
  • date_created:max in query - string
    Filter items by maximum date created, for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers created before this date.
  • date_created:min in query - string
    Filter items by date created for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers created after this date.
  • date_modified in query - string
    Filter items by date modified, for example, 2024-05-14T09:34:00 or 2024-05-14.
  • date_modified:min in query - string
    Filter items by minimum date modified, for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers modified after this date.
  • date_modified:max in query - string
    Filter items by maximum date modified, for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers modified before this date.
  • email:in in query - array
    Filter items by email. email:in=janedoe@example.com
    Type: array[string]
  • name:in in query - array
    Filter items by first_name and last_name. name=james moriarty
    Type: array[string]
  • name:like in query - array

    Filter items by substring in first_name and last_name. name:like=moriarty,sherlock Concatenates the first_name and last_name fields.

    Type: array[string]
  • phone:in in query - string
    Filter items by phone number. phone:in=555-55-5555
  • registration_ip_address:in in query - array

    Filter items by registration_ip_address. If the customer was created using the API, then registration address is blank. registration_ip_address:in=12.345.6.789

    Type: array[integer]
  • include in query - array

    Indicates whether to include customer sub-resources:

    • addresses
      • customer addresses
    • storecredit
      • store credit
    • attributes
      • customer attributes and address attributes
    • formfields
      • customer and address form fields
    • shopper_profile_id
      • the ID of the shopper profile associated with the customer (Beta)

    • segment_ids- segments the customer belongs to (Beta)

      include=addresses,storecredit,attributes,formfields,shopper_profile_id,segment_ids

    Type: array[string]

    Allowed: addresses | storecredit | attributes | formfields | shopper_profile_id | segment_ids

  • sort in query - string
    Sort items by date_created, date_modified, or last_name: date_created:asc - date created, ascending date_created:desc - date created, descending last_name:asc - last name, ascending last_name:desc - last name, descending date_modified:asc - date modified, ascending date_modified:desc- date modified, descending Example: sort=last_name:asc

    Allowed: date_created:asc | date_created:desc | last_name:asc | last_name:desc | date_modified:asc | date_modified:desc

  • after in query - string
    The cursor reference of the last entry for the previous page. Use the end_cursor value from the last response to get the next page (end_cursor is only returned on the first page or when the request contains query parameter before or after). For example after=eyJpZCI6MjA0fQ.
  • before in query - string
    The cursor reference of the first entry for the next page. Use the start_cursor value from the last response to get the previous page (start_cursor is only returned on the first page or when the request contains query parameter before or after). For example before=eyJpZCI6MjA1fQ.

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/customers' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Get Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals. Both pagination and cursor_pagination would be returned in the first page. Only pagination would be returned when page is greater than 1. Only cursor_pagination would be returned when before or after is provided in the request.

example-1

{
"data": [
{
"email": "string@example.com",
"first_name": "string",
"last_name": "string",
"company": "string",
"phone": "string",
"notes": "string",
"tax_exempt_category": "string",
"customer_group_id": 0,
"addresses": [
{
"first_name": "string",
"last_name": "string",
"address1": "Addr1",
"address2": "",
"city": "string",
"state_or_province": "string",
"postal_code": "string",
"country_code": "st",
"phone": "string",
"address_type": "residential",
"customer_id": 0,

Create Customers

POST /customers

Request

Creates Customers. Create up to 10 customers in one call.

Required Fields

  • last_name
  • first_name
  • email

Required Fields Customer Address

  • first_name
  • city
  • country_code
  • last_name
  • address1

Required Fields Attributes

  • Attributes must be created BEFORE creating a customer.
  • attribute_id
  • attribute_value -- This is input as a string, regardless of the Type.

Notes

A customer can be created with global access or channel-specific access.

  • Global access:
    • Make sure the channel has allow_global_logins enabled. This is on by default only for the default storefront. Find more info at Customer Settings > Channel.
    • Omit channel_ids field, or provide channel_ids: null.
  • Channel-specific access:
    • Provide a channel_ids array containing the channels accessible by the customer. This array cannot be empty.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string

Body

array | application/json

  • first_name    string
    required

    The first name of the customer.
    >= 1 characters<= 100 characters

  • last_name    string
    required

    The last name of the customer.
    >= 1 characters<= 100 characters

  • company    string

    The company of the customer.
    >= 0 characters<= 255 characters

  • phone    string

    The phone number of the customer.
    >= 0 characters<= 50 characters

  • notes    string

    The customer notes.

  • tax_exempt_category    string

    The tax exempt category code for the customer.
    >= 0 characters<= 255 characters

  • customer_group_id    integer

    ID of the group which this customer belongs to.

  • addresses    array[object]

    Array of customer addresses. Limited to 10.

  • attributes    array[object]

    Array of customer attributes. Limited to 10.

  • authentication    object

  • accepts_product_review_abandoned_cart_emails    boolean

    It determines if the customer is signed up to receive either product review or abandoned cart emails or receive both emails.

  • store_credit_amounts    array[object]

    Store credit.

  • origin_channel_id    integer

    Channel ID of the customer that has created the form.

  • channel_ids    array[integer]

    Array of channels the customer can access.
    Type: array[integer]
    Example: [1,2]

  • form_fields    array[object]

    Array of form fields. Controlled by formfields parameter.

example-1

[
{
"email": "string@example.com",
"first_name": "string",
"last_name": "string",
"company": "string",
"phone": "string",
"notes": "string",
"tax_exempt_category": "string",
"customer_group_id": 0,
"addresses": [
{
"address1": "Addr 1",
"address2": "",
"address_type": "residential",
"city": "San Francisco",
"company": "History",
"country_code": "US",
"first_name": "Ronald",
"last_name": "Swimmer",
"phone": "707070707",
"postal_code": "33333",
"state_or_province": "California",
"form_fields": [

Response

Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Response metadata.

example-1

{
"data": [
{
"email": "string@example.com",
"first_name": "string",
"last_name": "string",
"company": "string",
"phone": "string",
"notes": "string",
"tax_exempt_category": "string",
"customer_group_id": 0,
"addresses": [
{
"first_name": "string",
"last_name": "string",
"address1": "Addr1",
"address2": "",
"city": "string",
"state_or_province": "string",
"postal_code": "string",
"country_code": "st",
"phone": "string",
"address_type": "residential",
"customer_id": 0,
"id": 0,

Update Customers

PUT /customers

Request

Updates Customers. Subresource updates are not supported.

Required Fields

  • id -- ID of the Customer This must be included in the request body

Read Only Fields

  • id
  • registration_ip_address
  • date_created
  • date_modified
  • origin_channel_id

Limits

  • Limit of 10 customers per call.
  • Limit of 3 concurrent requests

Notes

  • Attributes Values can not be updated using Update a Customer. Use the Update customer attribute values endpoint.
  • channel_ids -- Updating the list of channels a customer can access may create some side effects in a multi-storefront situation. This list determines which customer account we will use to authenticate a shopper given a channel.
  • origin_channel_id -- This is an immutable value set as a reference to the channel of origin when a customer is created.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string

Body

array | application/json

  • first_name    string

    The first name of the customer.
    >= 1 characters<= 100 characters

  • last_name    string

    The last name of the customer.
    >= 1 characters<= 100 characters

  • company    string

    The company of the customer.
    >= 0 characters<= 255 characters

  • phone    string

    The phone number of the customer.
    >= 0 characters<= 50 characters

  • registration_ip_address    string

    The IP address from which this customer was registered.
    >= 0 characters<= 30 characters

  • notes    string

    The customer notes.

  • tax_exempt_category    string

    The tax exempt category code for the customer.
    >= 0 characters<= 255 characters

  • customer_group_id    integer

    ID of the group which this customer belongs to.

  • id    integer
    required

    The unique numeric ID of the customer.

  • authentication    object

  • accepts_product_review_abandoned_cart_emails    boolean

    It determines if the customer is signed up to receive either product review or abandoned cart emails or receive both emails.

  • store_credit_amounts    array[object]

    Store credit.

  • origin_channel_id    integer

    Channel ID of the customer that has created the form.

  • channel_ids    array[integer]

    Arrays of channels the customer can access.

  • form_fields    array[object]

    Array of form fields. Controlled by formfields parameter.

example-1

[
{
"email": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"phone": "string",
"registration_ip_address": "string",
"notes": "string",
"tax_exempt_category": "string",
"customer_group_id": 0,
"id": 1,
"authentication": {
"force_password_reset": true,
"new_password": "string123"
},
"accepts_product_review_abandoned_cart_emails": true,
"store_credit_amounts": [
{
"amount": 43.15
}
],
"origin_channel_id": 1,
"channel_ids": [
1
],
"form_fields": [
{

example-2-form-fields

[
{
"id": 1,
"form_fields": [
{
"name": "test",
"value": "test"
}
]
}
]

Response

Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Response metadata.

example-1

{
"data": [
{
"email": "string@example.com",
"first_name": "string",
"last_name": "string",
"company": "string",
"phone": "string",
"notes": "string",
"tax_exempt_category": "string",
"customer_group_id": 0,
"addresses": [
{
"first_name": "string",
"last_name": "string",
"address1": "Addr1",
"address2": "",
"city": "string",
"state_or_province": "string",
"postal_code": "string",
"country_code": "st",
"phone": "string",
"address_type": "residential",
"customer_id": 0,
"id": 0,

Delete Customers

DELETE /customers

Request

Deletes Customers.

Required Query

  • id:in -- ID of the customer

Notes

A query is required to delete customers. If not provided, a 204 is returned, with no changes to the data.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • id:in in query - array
    required

    Filter items by ID. id:in=4,5,6

    Type: array[integer]

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/customers' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Delete All CurrenciesGet All Customers