BigCommerce Customers is a platform that helps businesses of all sizes create, design, and manage their online stores. It offers a range of tools and features to help businesses sell products and services online, reach new customers, and grow their online presence. BigCommerce Customers provides a user-friendly interface, customizable themes, and reliable support to help businesses build successful online stores.
openapi: 3.0.0
info:
version: ''
title: BigCommerce Customers V3
description: |-
Create and manage customers.
## Resources
* [Customers Overview](/docs/store-operations/customers).
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Addresses
- name: Attribute Values
- name: Attributes
- name: Channel Settings
- name: Consent
- name: Customer Batch Metafields
- name: Customer Metafields
- name: Customers
- name: Form Field Values
- name: Global Settings
- name: Stored Instruments
- name: Validate Credentials
paths:
/customers:
get:
description: >-
Returns a list of Customers. Optional filter parameters can be passed
in.
**Notes**
Attribute names are not available on the customer object.
summary: BigCommerce Get All Customers
tags:
- Customers
operationId: getCustomers
deprecated: false
parameters:
- name: page
in: query
description: Page number. `page=1`
schema:
type: integer
- in: query
name: limit
description: Items count per page. `limit=50`
schema:
type: number
- name: id:in
in: query
description: |-
Filter items by ID.
`id:in=4,5,6`
style: form
explode: false
schema:
type: array
items:
type: integer
- name: company:in
in: query
description: Filter items by company. `company:in=bigcommerce,commongood`
style: form
explode: false
schema:
type: array
items:
type: string
- name: customer_group_id:in
in: query
description: Filter items by customer_group_id. `customer_group_id:in=5,6`
style: form
explode: false
schema:
type: array
items:
type: string
- name: date_created
in: query
description: Filter items by date_created. `date_created=2018-09-05T13:43:54`
schema:
type: string
format: date-time
- name: date_created:max
in: query
description: Filter items by maximum date_created. `date_created:max=2018-09-10`
schema:
type: string
- name: date_created:min
in: query
description: Filter items by date_created. `date_created:min=2018-09-05`
schema:
type: string
format: date-time
- name: date_modified
in: query
description: Filter items by date_modified. `date_modified=2018-09-05T13:45:03`
schema:
type: string
format: date-time
- name: date_modified:min
in: query
description: >-
Filter items by minimum date_modified.
`date_modified:min=2019-09-04T:00:00:00` or
`date_modified:min=2019-09-04`
schema:
type: string
- name: date_modified:max
in: query
description: >-
Filter items by maximum date_modified.
`date_modified:max=2018-09-05T13:45:03` or
`date_modified:max=2019-09-04`
schema:
type: string
format: date-time
- name: email:in
in: query
description: Filter items by email. `email:[email protected]`
schema:
type: string
- name: name:in
in: query
description: Filter items by first_name and last_name. `name=james moriarty`
style: form
explode: false
schema:
type: array
items:
type: string
- name: name:like
in: query
description: |-
Filter items by substring in first_name and last_name.
`name:like=moriarty, sherlock`
Concatenates the first_name and last_name fields.
style: form
explode: false
schema:
type: array
items:
type: string
- name: registration_ip_address:in
in: query
description: >-
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`
style: form
explode: false
schema:
type: array
items:
type: integer
- name: include
in: query
description: |-
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`
explode: false
schema:
type: array
items:
type: string
enum:
- addresses
- storecredit
- attributes
- formfields
- shopper_profile_id
- segment_ids
- in: query
name: sort
description: >-
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`
schema:
type: string
enum:
- date_created:asc
- date_created:desc
- last_name:asc
- last_name:desc
- date_modified:asc
- date_modified:desc
responses:
'200':
$ref: '#/components/responses/CustomerCollectionResponse'
post:
description: >-
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](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute)
**BEFORE** creating a customer.
* attribute_id
* attribute_value -- This is input as a string, regardless of the
[Type](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute).
**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](/docs/rest-management/customers/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.
summary: BigCommerce Create Customers
tags:
- Customers
operationId: createCustomers
deprecated: false
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/customer_Post'
examples:
example-1:
value:
- email: [email protected]
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:
- name: test
value: test
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:
- name: test
value: test
required: true
x-examples: {}
description: ''
responses:
'200':
$ref: '#/components/responses/CustomerCollectionResponse'
'413':
description: >-
The request payload is too large. The maximum number of items
allowed in the array is 10.
'422':
description: >-
The *Customer* was not valid. This is the result of missing required
fields or trying to edit a read only field. See the response for
more details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
status: 422
title: Create customers failed.
type: /api-docs/getting-started/api-status-codes
errors:
.customer_create: Error creating customers
put:
description: >-
Updates Customers. Subresource updates are not supported. Up to 10
customers can be updated in one call.
**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
**Notes**
* Attributes Values can not be updated using Update a Customer. Use the
[Update customer attribute
values](/docs/rest-management/customers/customer-attribute-values#upsert-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.
summary: BigCommerce Update Customers
tags:
- Customers
operationId: updateCustomers
deprecated: false
responses:
'200':
$ref: '#/components/responses/CustomerCollectionResponse'
'413':
description: >-
The request payload is too large. The maximum number of items
allowed in the array is 10.
'422':
description: >
The `Customer` was not valid. This is the result of missing required
fields, or of invalid data. See the response for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/customer_Put'
examples:
example-1:
value:
- 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:
- name: test
value: test
example-2-form-fields:
value:
- id: 1
form_fields:
- name: test
value: test
delete:
description: >-
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.
summary: BigCommerce Delete Customers
tags:
- Customers
operationId: deleteCustomers
deprecated: false
parameters:
- in: query
name: id:in
description: |-
Filter items by ID.
`id:in=4,5,6`
required: true
style: form
explode: false
schema:
type: array
items:
type: integer
responses:
'204':
description: ''
headers: {}
/customers/addresses:
get:
description: >-
Returns a list of Customer Addresses. Optional filter parameters can be
passed in.
summary: BigCommerce Get All Customer Addresses
operationId: getCustomersAddresses
deprecated: false
parameters:
- name: Accept
in: header
schema:
type: string
default: application/json
- name: Content-Type
in: header
schema:
type: string
default: application/json
- name: page
in: query
description: Page number. `page=1`
schema:
type: integer
- in: query
name: limit
description: Items count per page. `limit=50`
schema:
type: number
- name: company:in
in: query
description: Filter items by company. `company:in=bigcommerce,commongood`
style: form
explode: false
schema:
type: array
items:
type: string
- name: name:in
in: query
description: Filter items by first_name and last_name. `name:in=James+Moriarty`
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: customer_id:in
description: >-
Filter by the ID of the customer. Also accepts comma-separated IDs
to filter for multiple customers. `customer_id:in=23,24,55`
style: form
explode: false
schema:
type: array
items:
type: integer
- name: include
in: query
description: |-
Indicates whether to include customer address sub-resources:
* `formfields` - address form fields
`include=formfields`
schema:
type: string
enum:
- formfields
- name: id:in
in: query
description: |-
Filter items by ID.
`id:in=4,5,6`
style: form
explode: false
schema:
type: array
items:
type: integer
responses:
'200':
$ref: '#/components/responses/AddressCollectionResponse'
tags:
- Addresses
post:
description: >-
Creates a Customer Address. Multiple customer addresses can be created
in one call.
**Required Fields**
* **customer_id**
* **first_name**
* **last_name**
* **city**
* **country_code**
* **address1**
**Notes**
* A unique customer address is a combination of the following core
address fields:
* **customer_id**
* **first_name**
* **last_name**
* **company**
* **phone**
* **address_type**
* **address1**
* **address2**
* **city**
* **country_code**
* **state_or_province**
* **postal_code**
* An attempt to create an address that already exists will result in no
change to the address or custom form field values, an HTTP 200 return
code, and the address will be absent from the response body.
* The default rate limit for this endpoint is 10 concurrent requests.
summary: BigCommerce Create a Customer Address
operationId: createCustomersAddresses
deprecated: false
parameters:
- name: Accept
in: header
schema:
type: string
default: application/json
- name: Content-Type
in: header
schema:
type: string
default: application/json
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/address_Post'
examples:
example-1:
value:
- first_name: John
last_name: Doe
address1: 111 E West Street
address2: '654'
city: Akron
state_or_province: Ohio
postal_code: '44325'
country_code: US
phone: '1234567890'
address_type: residential
customer_id: 11
form_fields:
- name: test
value: test
required: true
x-examples:
application/json:
- first_name: John
last_name: Doe
address1: 111 E West Street
address2: '654'
city: Akron
state_or_province: Ohio
postal_code: '44325'
country_code: US
phone: '1234567890'
address_type: residential
customer_id: 11
form_fields:
- name: test
value: test
responses:
'200':
$ref: '#/components/responses/AddressCollectionResponsePostPut'
'422':
description: >
The `Address` was not valid. This is the result of missing required
fields, or of invalid data. See the response for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Addresses
put:
description: >-
Updates a Customer Address. Multiple customer addresses can be updated
in one call.
**Required Fields**
* **id** -- ID of the *Customer Address*
**Limits**
* Limit of **3** concurrent requests.
**Notes**
* A unique customer address is a combination of the following core
address fields:
* **first_name**
* **last_name**
* **company**
* **phone**
* **address_type**
* **address1**
* **address2**
* **city**
* **country_code**
* **state_or_province**
* **postal_code**
* An attempt to update an address such that it becomes identical to
another address that already exists will result in no change to the
target address or custom form field values. The response will have an
HTTP 200 return code, and the address will be absent from the response
body.
summary: BigCommerce Update a Customer Address
operationId: updateCustomersAddresses
deprecated: false
parameters:
- name: Accept
in: header
schema:
type: string
default: application/json
- name: Content-Type
in: header
schema:
type: string
default: application/json
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/address_Put'
examples:
example-1:
value:
- id: 11
first_name: John
last_name: Doe
address1: 111 E West Street
address2: '654'
city: Akron
state_or_province: Ohio
postal_code: '44325'
country_code: US
phone: '1234567890'
address_type: residential
form_fields:
- name: test
value: test
example-2-form-fields:
value:
- id: 11
form_fields:
- name: test
value: test
required: true
x-examples:
application/json:
- first_name: John
last_name: Doe
id: 38
address1: 111 E West Street
address2: '654'
city: Akron
state_or_province: Ohio
postal_code: '44325'
country_code: US
phone: '1234567890'
address_type: residential
responses:
'200':
$ref: '#/components/responses/AddressCollectionResponsePostPut'
'422':
description: >
The `Address` was not valid. This is the result of missing required
fields, or of invalid data. See the response for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Addresses
delete:
description: |-
Deletes a Customer Address.
**Required Query**
* id:in -- ID of the *Customer Address*
summary: BigCommerce Delete a Customer Address
operationId: deleteCustomersAddresses
deprecated: false
parameters:
- name: Accept
in: header
schema:
type: string
default: application/json
- name: Content-Type
in: header
schema:
type: string
default: application/json
- in: query
name: id:in
required: true
description: |-
Filter items by ID.
`id:in=4,5,6`
style: form
explode: false
schema:
type: array
items:
type: integer
responses:
'204':
description: ''
headers: {}
tags:
- Addresses
/customers/validate-credentials:
post:
tags:
- Validate Credentials
description: >-
Validate a customer credentials - This endpoint has special rate
limiting protections to protect against abuse.
summary: BigCommerce Validate a customer credentials
operationId: validateCustomerCredentials
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateCustomerCredentialsObject'
examples:
data:
value:
email: [email protected]
password: password
channel_id: 1
responses:
'200':
description: Returns if the customer credentials provided are valid or not.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateCustomerCredentialsResponseObject'
examples:
data:
value:
is_valid: true
customer_id: 1
'422':
description: >-
This is the result of missing required fields. See the response for
more details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: |
Allowed number of requests exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
status: 429
title: Too many requests
type: /api-docs/getting-started/api-status-codes
errors: {}
/customers/settings:
get:
tags:
- Global Settings
description: Returns the global-level customer settings.
summary: BigCommerce Get Customer Settings
operationId: getCustomersSettings
responses:
'200':
description: Returns customer settings values for global level.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSettingsObject'
examples:
data:
value:
privacy_settings:
ask_shopper_for_tracking_consent: true
policy_url: https://bigcommmerce.com/policy
customer_group_settings:
guest_customer_group_id: 1
default_customer_group_id: 1
put:
tags:
- Global Settings
description: Updates the customer settings on the global level.
summary: BigCommerce Update Customer Settings
operationId: updateCustomersSettings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSettingsObject'
examples:
example-1:
value:
privacy_settings:
ask_shopper_for_tracking_consent: true
policy_url: https://bigcommmerce.com/policy
customer_group_settings:
guest_customer_group_id: 0
default_customer_group_id: 0
required: true
responses:
'200':
description: Customer settings are returned on a global level.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSettingsObject'
examples:
data:
value:
privacy_settings:
ask_shopper_for_tracking_consent: true
policy_url: https://bigcommerce.com/policy
ask_shopper_for_tracking_consent_on_checkout: false
customer_group_settings:
guest_customer_group_id: 0
default_customer_group_id: 0
/customers/settings/channels/{channel_id}:
get:
tags:
- Channel Settings
description: |-
Returns the customer settings per channel.
**Notes**
* `null` indicates that there is no override per given channel and values are inherited from the global level.
summary: BigCommerce Get Customer Settings per Channel
operationId: getCustomersSettingsChannel
parameters:
- in: path
name: channel_id
schema:
type: integer
required: true
responses:
'200':
description: Customer settings for this channel are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerChannelSettingsObject'
examples:
data:
value:
privacy_settings:
ask_shopper_for_tracking_consent: true
policy_url: https://bigcommmerce.com/policy
customer_group_settings:
guest_customer_group_id: 1
allow_global_logins: true
put:
tags:
- Channel Settings
description: >-
Update the customer settings per channel
**Required Fields**
* `channel_id`: Provide a `channel_id` array containing one or more
channel IDs. Customers will have access to these channels and no others.
This array cannot be empty.
**Notes**
* Setting `null` will delete override per given channel, and values will
be inherited from the global level. Make sure the channel has
`allow_global_logins` enabled.
summary: BigCommerce Update Customer Settings per Channel
operationId: updateCustomersSettingsChannel
parameters:
- in: path
name: channel_id
schema:
type: integer
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerChannelSettingsObject'
examples:
example-1:
value:
privacy_settings:
ask_shopper_for_tracking_consent: true
policy_url: https://bigcommmerce.com/policy
customer_group_settings:
guest_customer_group_id: 0
default_customer_group_id: 0
allow_global_logins: true
required: true
responses:
'200':
description: Customer settings are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSettingsObject'
examples:
example:
value:
privacy_settings:
ask_shopper_for_tracking_consent: true
policy_url: https://bigcommmerce.com/policy
ask_shopper_for_tracking_consent_on_checkout:
customer_group_settings:
guest_customer_group_id: 0
default_customer_group_id: 0
allow_global_logins: true
parameters:
- schema:
type: string
name: channel_id
in: path
required: true
/customers/attributes:
get:
description: >-
Returns a list of Customer Attributes. You can pass in optional filter
parameters.
summary: BigCommerce Get All Customer Attributes
operationId: getCustomersAttributes
deprecated: false
parameters:
- name: page
in: query
description: Page number. `page=1`
schema:
type: integer
- in: query
name: limit
description: Items count per page. `limit=50`
schema:
type: number
- na
# --- truncated at 32 KB (166 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/customers-openapi-original.yml