Thanks for being patient while we implement your feedback to improve the developer experience.

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

  • company:in in query - array

    Filter items by company. company:in=bigcommerce,commongood

  • customer_group_id:in in query - array

    Filter items by customer_group_id. customer_group_id:in=5,6

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

    Filter items by email. email:in=janedoe@example.com

  • name:in in query - array

    Filter items by first_name and last_name. name=james moriarty

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

  • 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

  • include in query - string

    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

  • 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

example

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

Response

Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

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,
          "country": "string"
        }
      ],
      "store_credit_amounts": [
        {
          "amount": 43.15
        }
      ],
      "accepts_product_review_abandoned_cart_emails": true,
      "channel_ids": [
        1
      ],
      "shopper_profile_id": "82511e54-4040-40fe-b742-2b25655f205b",
      "segment_ids": [
        "5bb733a9-5491-47b3-9451-9ae8d6a6bc6b"
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "per_page": 0,
      "current_page": 0,
      "total_pages": 0,
      "links": {
        "previous": "string",
        "current": "string",
        "next": "string"
      }
    }
  }
}

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.

Limits

  • Limit of 10 concurrent requests

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

    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

  • 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": [
          {
            "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"
      }
    ]
  }
]

Response

Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

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,
          "country": "string"
        }
      ],
      "store_credit_amounts": [
        {
          "amount": 43.15
        }
      ],
      "accepts_product_review_abandoned_cart_emails": true,
      "channel_ids": [
        1
      ],
      "shopper_profile_id": "82511e54-4040-40fe-b742-2b25655f205b",
      "segment_ids": [
        "5bb733a9-5491-47b3-9451-9ae8d6a6bc6b"
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "per_page": 0,
      "current_page": 0,
      "total_pages": 0,
      "links": {
        "previous": "string",
        "current": "string",
        "next": "string"
      }
    }
  }
}

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

    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",
    "notes": "string",
    "tax_exempt_category": "string",
    "customer_group_id": 0,
    "id": 1,
    "addresses": [
      {
        "address1": "string",
        "address2": "string",
        "address_type": "string",
        "city": "string",
        "company": "string",
        "country_code": "string",
        "first_name": "string",
        "last_name": "string",
        "phone": "string",
        "postal_code": "string",
        "state_or_province": "string"
      }
    ],
    "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

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

Response

Customer Collection Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

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,
          "country": "string"
        }
      ],
      "store_credit_amounts": [
        {
          "amount": 43.15
        }
      ],
      "accepts_product_review_abandoned_cart_emails": true,
      "channel_ids": [
        1
      ],
      "shopper_profile_id": "82511e54-4040-40fe-b742-2b25655f205b",
      "segment_ids": [
        "5bb733a9-5491-47b3-9451-9ae8d6a6bc6b"
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "per_page": 0,
      "current_page": 0,
      "total_pages": 0,
      "links": {
        "previous": "string",
        "current": "string",
        "next": "string"
      }
    }
  }
}

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

example

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

Response