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
    required

Parameters

  • store_hash in path - string
  • page in query - integer

    Page number. 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. date_created=2018-09-05T13:43:54

  • date_created:max in query - string

    Filter items by maximum date_created. date_created:max=2018-09-10

  • date_created:min in query - string

    Filter items by date_created. date_created:min=2018-09-05

  • date_modified in query - string

    Filter items by date_modified. date_modified=2018-09-05T13:45:03

  • date_modified:min in query - string

    Filter items by minimum date_modified. date_modified:min=2019-09-04T:00:00:00 or date_modified:min=2019-09-04

  • date_modified:max in query - string

    Filter items by maximum date_modified. date_modified:max=2018-09-05T13:45:03 or date_modified:max=2019-09-04

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

  • 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

example

Response

Customer Collection Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

example-1

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
    required

Parameters

  • store_hash in path - string

Body

array | application/json
  • email
    string
    required

    The email of the customer. Must be unique.

    >= 3 characters<= 255 characters
  • 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

Response

Customer Collection Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

example-1

Update Customers

PUT /customers

Request

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

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string

Body

array | application/json
  • email
    string

    The email of the customer. Must be unique.

    >= 3 characters<= 255 characters
  • 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

example-2-form-fields

Response

Customer Collection Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

example-1

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
    required

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

Response

Did you find what you were looking for?