# Create a customer group

URL: https://docs.sparklayer.io/developers/api/core/new-customer-group
Operation: `POST /api/v1/customer-groups` (operationId `createCustomerGroup`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Creates a customer group and returns the full, updated list of groups. `parent_slug` defaults to `base` and must be an existing group. A `slug` that's already in use returns `400` (`resource-already-exists`), and an unknown parent returns `400` (`resource-id-not-found`).

`POST /api/v1/customer-groups`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/customer-groups" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "eu_gbp",
  "name": "Europe (GBP) Customers",
  "parent_slug": "base"
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | A unique identifier for the group: lowercase letters, numbers, `-`, `~` and `_`, starting with a letter. It can't be `null` or `default`. Length: max 128. Pattern: `^(?!^null$)(?!^default$)[a-z]([a-z0-9\-~_]*$)`. |
| `name` | string | Yes | The group's display name. Length: max 256. |
| `parent_slug` | string | | The slug of an existing group to inherit from. Defaults to `base`. Length: max 128. |

```json
{
  "slug": "eu_gbp",
  "name": "Europe (GBP) Customers",
  "parent_slug": "base"
}
```

### Responses

#### 200: Every customer group, including the new one.

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].slug` | string | Yes | Length: max 128. |
| `[].name` | string | Yes | Length: max 256. |
| `[].parent_slug` | string | | Length: max 128. |

```json
[
  {
    "slug": "eu_gbp",
    "name": "Europe (GBP) Customers",
    "parent_slug": "base"
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```