Docs
Management API
Customers V2
Customer Groups

Customer Groups

Get All Customer Groups

GET /customer_groups

Request

Returns a list of Customer Groups. Default sorting is by customer-group ID, from lowest to highest.

Note: The default rate limit for this endpoint is 40 concurrent requests.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • page in query - number
    Number of pages.
  • limit in query - number
    Count per page.
  • name in query - string
    Filter customer groups by exact name match.
  • name:like in query - string
    Filter customer groups by name, using a fuzzy matching method.
  • is_default in query - boolean
    Filter by customers who sign up are added to this group by default.
  • date_created in query - string
    Filter customer groups by date_created. date_created=2018-09-05T13:43:54
  • date_created:max in query - string
    Filter customer groups by maximum date_created. date_created:max=2018-09-10
  • date_created:min in query - string
    Filter customer groups by date_created. date_created:min=2018-09-05
  • date_modified in query - string
    Filter customer groups by date_modified. date_modified=2018-09-05T13:45:03
  • date_modified:min in query - string
    Filter customer groups 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 customer groups by maximum date_modified. date_modified:max=2018-09-05T13:45:03 or date_modified:max=2019-09-04
  • is_group_for_guests in query - boolean
    Filter whether the group is for guests. There can only be one customer group for guests at a time.

example

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

Response

Body

array | application/json

  • id    integer

    ID of the customer group.
    Example: 1

  • name    string

    Name of the group.
    Example: Wholesale

  • is_default    boolean

    Determines whether new customers are assigned to this group by default.

  • category_access    object

  • discount_rules

    One of:

    • type      string

      Allowed: price_list | all | category | product

    • method      string

      Allowed: percent | fixed | price

    • amount      string

      A float that specifies the value applied to the price modified. (Float, Float as String, Integer)
      Example: 5.0000

    • price_list_id      integer

      If a customer group is assigned to a price list,method and amount are not shown. type and price_list_id are returned.
      Example: 3

  • date_created    string

    Date on which the customer group was created.
    Example: 2023-07-17 06:30:41

  • date_modified    string

    Date on which the customer group was last modified.
    Example: 2023-07-25 01:15:19

  • is_group_for_guests    boolean

    Describes whether the group is for guests. There can only be one customer group for guests at a time.

example

[
{
"id": 1,
"name": "Wholesale",
"is_default": false,
"category_access": {
"type": "all",
"categories": [
18,
19,
23,
34
]
},
"discount_rules": [
{
"type": "price_list",
"method": "percent",
"amount": "5.0000",
"price_list_id": 3
}
],
"date_created": "2023-07-17 06:30:41",
"date_modified": "2023-07-25 01:15:19",
"is_group_for_guests": true
}
]

Create a Customer Group

POST /customer_groups

Request

Creates a Customer Group.

Required Fields

  • name

Note: The default rate limit for this endpoint is 40 concurrent requests.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the store control panel, this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API.

  • name    string

    Name of the group.
    Example: Wholesale

  • is_default    boolean

    Determines whether new customers are assigned to this group by default.

  • category_access    object

  • discount_rules

    One of:

    • type      string
      required

      Allowed: price_list

    • price_list_id      integer

      If a customer group is assigned to a price list,method and amount are not shown. type and price_list_id are returned.
      Example: 3

  • is_group_for_guests    boolean

    Describes whether the group is for guests. There can only be one customer group for guests at a time.

example

{
"name": "Wholesale",
"is_default": false,
"category_access": {
"type": "all",
"categories": [
18,
19,
23,
34
]
},
"discount_rules": [
{
"type": "price_list",
"price_list_id": 3
}
],
"is_group_for_guests": true
}

Response

Body

object | application/json
When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the store control panel, this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API.

  • id    integer

    ID of the customer group.
    Example: 1

  • name    string

    Name of the group.
    Example: Wholesale

  • is_default    boolean

    Determines whether new customers are assigned to this group by default.

  • category_access    object

  • discount_rules

    One of:

    • type      string

      Allowed: price_list | all | category | product

    • method      string

      Allowed: percent | fixed | price

    • amount      string

      A float that specifies the value applied to the price modified. (Float, Float as String, Integer)
      Example: 5.0000

    • price_list_id      integer

      If a customer group is assigned to a price list,method and amount are not shown. type and price_list_id are returned.
      Example: 3

  • date_created    string

    Date on which the customer group was created.
    Example: 2023-07-17 06:30:41

  • date_modified    string

    Date on which the customer group was last modified.
    Example: 2023-07-25 01:15:19

  • is_group_for_guests    boolean

    Describes whether the group is for guests. There can only be one customer group for guests at a time.

example

{
"id": 1,
"name": "Wholesale",
"is_default": false,
"category_access": {
"type": "all",
"categories": [
18,
19,
23,
34
]
},
"discount_rules": [
{
"type": "price_list",
"method": "percent",
"amount": "5.0000",
"price_list_id": 3
}
],
"date_created": "2023-07-17 06:30:41",
"date_modified": "2023-07-25 01:15:19",
"is_group_for_guests": true
}

Get a Customer Group

GET /customer_groups/{customer_group_id}

Request

Returns a Customer Group.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • customer_group_id in path - integer
    required
    The ID of the customer group.
  • page in query - number
    Number of pages.
  • limit in query - number
    Count per page.
  • name in query - string
    Name of the customer groups.
  • 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
  • is_default in query - boolean
    Whether customers who sign up are added to this group by default.

example

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

Response

The request was successful.

Body

object | application/json
When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the store control panel, this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API.

  • id    integer

    ID of the customer group.
    Example: 1

  • name    string

    Name of the group.
    Example: Wholesale

  • is_default    boolean

    Determines whether new customers are assigned to this group by default.

  • category_access    object

  • discount_rules

    One of:

    • type      string

      Allowed: price_list | all | category | product

    • method      string

      Allowed: percent | fixed | price

    • amount      string

      A float that specifies the value applied to the price modified. (Float, Float as String, Integer)
      Example: 5.0000

    • price_list_id      integer

      If a customer group is assigned to a price list,method and amount are not shown. type and price_list_id are returned.
      Example: 3

  • date_created    string

    Date on which the customer group was created.
    Example: 2023-07-17 06:30:41

  • date_modified    string

    Date on which the customer group was last modified.
    Example: 2023-07-25 01:15:19

  • is_group_for_guests    boolean

    Describes whether the group is for guests. There can only be one customer group for guests at a time.

example

{
"id": 1,
"name": "Wholesale",
"is_default": false,
"category_access": {
"type": "all",
"categories": [
18,
19,
23,
34
]
},
"discount_rules": [
{
"type": "price_list",
"method": "percent",
"amount": "5.0000",
"price_list_id": 3
}
],
"date_created": "2023-07-17 06:30:41",
"date_modified": "2023-07-25 01:15:19",
"is_group_for_guests": true
}

Update a Customer Group

PUT /customer_groups/{customer_group_id}

Request

Updates a Customer Group.

Notes

Any combination of fields can be updated at once. Discount rules are treated in bulk. The entire set of rules is overwritten when a request is sent.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • customer_group_id in path - integer
    required
    The ID of the customer group.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the store control panel, this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API.

  • name    string

    Name of the group.
    Example: Wholesale

  • is_default    boolean

    Determines whether new customers are assigned to this group by default.

  • category_access    object

  • discount_rules

    One of:

    • type      string
      required

      Allowed: price_list

    • price_list_id      integer

      If a customer group is assigned to a price list,method and amount are not shown. type and price_list_id are returned.
      Example: 3

  • is_group_for_guests    boolean

    Describes whether the group is for guests. There can only be one customer group for guests at a time.

example

{
"name": "Wholesale",
"is_default": false,
"category_access": {
"type": "all",
"categories": [
18,
19,
23,
34
]
},
"discount_rules": [
{
"type": "price_list",
"price_list_id": 3
}
],
"is_group_for_guests": true
}

Response

Body

object | application/json
When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the store control panel, this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API.

  • id    integer

    ID of the customer group.
    Example: 1

  • name    string

    Name of the group.
    Example: Wholesale

  • is_default    boolean

    Determines whether new customers are assigned to this group by default.

  • category_access    object

  • discount_rules

    One of:

    • type      string

      Allowed: price_list | all | category | product

    • method      string

      Allowed: percent | fixed | price

    • amount      string

      A float that specifies the value applied to the price modified. (Float, Float as String, Integer)
      Example: 5.0000

    • price_list_id      integer

      If a customer group is assigned to a price list,method and amount are not shown. type and price_list_id are returned.
      Example: 3

  • date_created    string

    Date on which the customer group was created.
    Example: 2023-07-17 06:30:41

  • date_modified    string

    Date on which the customer group was last modified.
    Example: 2023-07-25 01:15:19

  • is_group_for_guests    boolean

    Describes whether the group is for guests. There can only be one customer group for guests at a time.

example

{
"id": 1,
"name": "Wholesale",
"is_default": false,
"category_access": {
"type": "all",
"categories": [
18,
19,
23,
34
]
},
"discount_rules": [
{
"type": "price_list",
"method": "percent",
"amount": "5.0000",
"price_list_id": 3
}
],
"date_created": "2023-07-17 06:30:41",
"date_modified": "2023-07-25 01:15:19",
"is_group_for_guests": true
}

Delete a Customer Group

DELETE /customer_groups/{customer_group_id}

Request

Deletes a Customer Group.

Notes

  • All existing customers are unassigned from the group when it is deleted.
  • The default rate limit for this endpoint is 40 concurrent requests.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • customer_group_id in path - integer
    required
    The ID of the customer group.

example

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

Response

No content. Request was successful but produced no response.

Get a Count of Customer Groups

GET /customer_groups/count

Request

Returns a count of all Customer Groups.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.

example

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

Response

Body

object | application/json

  • count    number

    Example: 27

example

{
"count": 27
}
Did you find what you were looking for?
Get a Count of Customer AddressesGet All Customer Groups