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

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

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

Response

Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Response metadata.

example-1

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

example-2-form-fields

Response

Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Response metadata.

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

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

See something you can improve? Edit this file on GitHub

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